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Preface 





Intended Audience 


This manual is intended for programmers who want to invoke and 
manipulate VMS utilities from a program. 





Document Structure 


This document contains 13 chapters. Chapter 1 introduces the utility routines 
and describes the documentation format used to describe each set of utility 
routines, as well as the individual routines in each set. 


Chapters 2 through 13 each describe one set of utility routines. Each chapter 

contains an introduction to that set of utility routines, a programming example 
to illustrate the use of the routines in the set, and a detailed decription of each 
routine. 





Associated Documents 


The VAX Procedure Calling and Condition Handling Standard, which is 
documented in the Introduction to VMS System Routines, contains useful 
information for all programmers. The Introduction to VMS System Routines 
also describes in detail the documentation format of the routine descriptions. 


Some sets of utility routines documented in this manual invoke and 
manipulate utilities that have a command level interface. Consult the 
following manuals for a description of the command level interface: 


e VMS Access Control List Editor Manual 

e VMS Command Definition Utility Manual 

e VMS Convert and Convert/Reclaim Utility Manual 
e VAX EDT Reference Manual 

e VMS File Definition Language Facility Manual 

e = VMS Librarian Utility Manual 

e =VMS Sort/Merge Utility Manual 

e VAX Text Processing Utility Manual 

e =VMS National Character Set Utility Manual 


Preface 





Conventions 


xvi 


The documentation template for utility routines, which is described in the 
Introduction to VMS System Routines, details the conventions used in this 
manual, as well as the organizational approach used to document each utility 


routine. 


The following table describes additional conventions that may appear in this 


manual. 


Convention 


CTRL/C 


$ SHOW TIME 
O5-JUN-1988 11:55:22 


$ TYPE MYFILE.DAT 


input-file, . 


[logical-name] 


quotation marks 
apostrophes 


Meaning 


In examples, a key name (usually abbreviated) 
shown within a box indicates that you press 

a key on the keyboard; in text, a key name is 
not enclosed in a box. In this example, the key 
is the RETURN key. (Note that the RETURN 
key is not usually shown in syntax statements 
or in all examples; however, assume that you 
must press the RETURN key after entering a 
command or responding to a prompt.) 


A key combination, shown in uppercase with a 
slash separating two key names, indicates that 
you hold down the first key while you press the 
second key. For example, the key combination 
CTRL/C indicates that you hold down the key 
labeled CTRL while you press the key labeled C. 
In examples, a key combination is enclosed in a 
box. 


In examples, system output (what the system 
displays) is shown in black. User input (what 
you enter) is shown in red. 


In examples, a vertical series of periods, or 
ellipsis, means either that not all the data that 
the system would display in response to a 
command is shown or that not all the data a 
user would enter is shown. 


In examples, a horizontal ellipsis indicates 
that additional parameters, values, or other 
information can be entered, that preceding 
items can be repeated one or more times, or 
that optional arguments in a statement have 
been omitted. 


Brackets indicate that the enclosed item is 
optional. (Brackets are not, however, optional 
in the syntax of a directory name in a file 
specification or in the syntax of a substring 
specification in an assignment statement.) 


The term quotation marks is used to refer 
to double quotation marks ("). The term 
apostrophe (‘) is used to refer to a single 
quotation mark. 


New and Changed Features 


New Set of Utility Routines 


The following set of utility routines is new for VMS Version 5.0: 


National Character Set (NCS) Utility routines 





New Utility Routines 


A new routine has been added to the VAX Text Processing Utility routines: 
TPU$CLOSE_TERMINAL 

A new routine has been added to the SORT/MERGE Utility routines: 
SOR$DTYPE 


xvii 


1 


1.1 


Introduction to Utility Routines 


Overview 





A set of utility routines performs a particular task or set of tasks. For example, 
you can use the Print Symbiont Modification (PSM) routines to modify the 
VMS print symbiont, and the EDT routines to invoke the EDT editor from a 
program. 


Some of the tasks performed by utility routines can also be performed at the 
DCL level (for example, the DCL command EDIT invokes the EDT editor). 
While DCL commands invoke VMS utilities that allow you to perform tasks 
at your terminal, you can perform some of these tasks at the programming 
level through the use of the utility routines. 


When using a set of utility routines that performs the same tasks as a VMS 
utility, you should read the documentation for that utility; doing so will 
provide additional information about the tasks the routines can perform as 
a set. Following is a list of VMS utilities that have corresponding utility 
routines. 


Utility or Editor Utility Routines 
Access Control List Editor ACL Editor routine 
Command Definition Utility CLI routines 
Convert and Convert/Reclaim Utilities CONV routines 
EDT Editor EDT routines 

File Definition Language Facility FDL routines 
Library Utility LBR routines 

VMS National Character Set Utility NCS routines 
Sort/Merge Utility SOR routines 
VAX Text Processing Utility VAXTPU routines 


When a set of utility routines performs functions that you cannot perform 
by invoking a VMS utility, the functions provided by that set of routines is 
termed a facility. The following facilities have no other user interface except 
the programming interface provided by the utility routines described in this 
manual. 


Facility Utility Routines 
Data Compression/Expansion Facility DCX routines 
Print Symbiont Modification Facility PSM routines 
Symbiont/Job-Controller Interface Facility SMB routines 


Introduction to Utility Routines 


1.1 Overview 


The utility routines described in this manual are called in the same way as all 
other system routines in the VMS operating system environment, which is to 
say that utility routines conform to the VAX Procedure Calling and Condition 
Handling Standard. 


Each chapter of this book documents one set of utility routines. Each chapter 
has the following major components, documented as a major heading: 


e An introduction to the set of utility routines. This component discusses 
the utility routines as a group and explains how to use them. 


e A series of descriptions of each utility routine in the set. 


Most of the chapters also include a programming example that illustrates how 
the utility routines are used. 


2.1 


2.2 


Access Control List (ACL) Editor Routine 





Introduction to the ACL Editor Routine 


This chapter describes the Access Control List (ACL) routine, ACLEDIT$EDIT. 
User-written applications can use this callable interface of the ACL Editor to 
manipulate Access Control Lists. 


The ACL Editor is a VMS utility that allows you to create and maintain 
access control lists. Using ACLs, you can fine-tune the type of access to files, 
devices, global sections, logical name tables, or mailboxes available to system 
users. 


Currently, the ACL Editor provides one callable interface that allows the 
application program to define an object for editing. 


Example of Using the ACL Editor Routine 
Example 2-1 shows a VAX BLISS program that calls the ACL Editor routine. 
Example 2—1 Calling the ACL Editor with a VAX BLISS Program 


MODULE MAIN (LANGUAGE (BLISS32), MAIN = STARTUP) = 
. BEGIN 

LIBRARY 'SYS$LIBRARY:LIB'; 

ROUTINE STARTUP = 

BEGIN 


LOCAL 

STATUS, ! Routine return status 

ITMLST : BLOCKVECTOR [6, ITM$S_ITEM, BYTE]; 
! ACL editor item list 


EXTERNAL LITERAL 
ACLEDIT$V_JOURNAL, 
ACLEDIT$V_PROMPT_MODE , 


ACLEDIT$C_OBJNAM, 
ACLEDIT$C_OBJTYP, 
ACLEDIT$C_OPTIONS ; 


EXTERNAL ROUTINE 
ACLEDIT$EDIT : ADDRESSING_MODE (GENERAL), ! Main routine 


CLI$GET_VALUE, ! Get qualifier value 
CLI$PRESENT, ! See if qualifier present 
LIB$PUT_OUTPUT, ! General output routine 
STR$COPY_DX; ! Copy string by descriptor 


Example 2—1 Cont'd. on next page 
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Access Control List (ACL) Editor Routine 
2.2 Example of Using the ACL Editor Routine 


Example 2—1 (Cont.) Calling the ACL Editor with a VAX BLISS 
Program 


! Set up the item list to 


CH$FILL (0, 6*ITM$S_ITEM, 
ITMLST(O, ITM$W_ITMCOD] 
ITMLST[O, ITM$W_BUFSIZ] 
ITMLST[O, ITM$L_BUFADR] 
ITMLST(1, ITM$W_ITMCOD] 
ITMLST[1, ITM$W_BUFSIZ] 
ITMLST[1, ITM$L_BUFADR] 
ITMLST(2, ITM$W_ITMCOD] 
ITMLST[2, ITM$W_BUFSIZ] 
ITMLST([2, ITM$L_BUFADR] 


pass back to TPU so it can figure out what to do. 


ITMLST) ; 

ACLEDIT$C_OBJNAM; 

%CHARCOUNT ('YOUR_OBJECT_NAME') ; 
$DESCRIPTOR ('YOUR_OBJECT_NAME') ; 
ACLEDIT$C_OBJTYP; 

4; 

UPLIT (ACL$C_FILE) ;: 
ACLEDIT$C_OPTIONS; 

4; 

UPLIT (1 * ACLEDIT$V_PROMPT_MODE OR 


1 * ACLEDIT$V_JOURNAL) ; 


RETURN ACLEDIT$EDIT (ITMLST) ; 
END ; ! End of routine STARTUP 


END 
ELUDOM 





2.3 ACL Editor Routine 
The following pages describe the ACL Editor routine. 
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ACLEDITSEDIT Edit Access Control List 


The ACLEDIT$EDIT routine is used to create and modify an Access 
Control List (ACL) associated with any system object. 











FORMAT ACLEDITS$SEDIT  item_list 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 
ARGUMENT item_list 
VMS usage: item_—list_3 
type: longword (unsigned) 
access: read only 


mechanism: by descriptor 


Item list used by the callable ACL Editor. The item_—list argument is the 
address of one or more descriptors of arrays, routines, or longword bit masks 
that control various aspects of the editing session. 


Each entry in an item list is in the standard format shown in Figure 2-1. 


Figure 2—1_ Item List 


buffer address 
return length address 


ZK-5012-86 
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Following is a detailed description of each item list entry. 


item Identifier Description 

ACLEDIT$C_OBJNAM Specifies the name of the object whose ACL is 
being edited. 

ACLEDIT$C_OBJTYP Specifies the type of the object whose ACL is being 


edited. These type codes are defined in $ACLDEF. 
The default object type is a file (ACLSC_FILE). 


ACLEDIT$C_OPTIONS Represents a longword bit mask of the various 
options available to control the editing session. 


Flag . Function 
ACLEDIT$V_JOURNAL Indicates that the 


editing session is 
to be journaled. 


ACLEDIT$V_.RECOVER Indicates that the 
editing session is 
to be recovered 
from an existing 
journal file. 


ACLEDIT$V_KEEP_RECOVER Indicates that the 
journal file used 
to recover the 
editing session 
is not to be 
deleted when 
the recovery is 
complete. 


ACLEDIT$ V_KEEP_JOURNAL Indicates that the 
journal file used 
for the editing 
session is not to 
be deleted when 
the session ends. 


ACLEDIT$V_PROMPT_MODE Indicates that 
the session is to 
use automatic 
text insertion 
(prompting) to 
build new access 
control list 
entries (ACEs). 


ACLEDIT$C_BIT_T ABLE Specifies a vector of quadword descriptors to be 
used when parsing or formatting an ACE, which will 
define the names of the bits present in the access 
mask, 
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DESCRIPTION You use the ACLEDIT$EDIT routine to create and modify an ACL associated 
with any system object. 


Under normal circumstances, the application calls the ACL Editor to modify 
an object’s ACL, and control is returned to the application when you finish or 
abort the editing session. | 


If you also want to use a customized version of the ACL Editor section file, 
the logical name ACLEDT$SECTION should be defined. See the VMS Access 
Control List Editor Manual for more information. 





CONN RMS$ See the VMS R dM. Services M / 
_XXX ee the ecord Management Services Manua 

VALUES for a description of RMS status codes. 

RETURNED TPU$_xxx See Chapter 13 for a description of the TPU- 


specific condition values that may be returned by 
ACLEDITS$EDIT. 
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3.1 Introduction to CLI Routines 


You use the CLI routines to process command strings using information 
from a command table. A command table contains command definitions 
that describe the allowable formats for commands. To create or modify 

a command table, you must write a command definition file and then . 
process this file with the Command Definition Utility (the SET COMMAND 
command). For information about how to use the Command Definition 
Utility, see the VMS Command Definition Utility Manual. 


The CLI routines include the following: 
e CLI$DCL_PARSE 

e CLI$DISPATCH 

e CLI$GET_VALUE 

e CLI$PRESENT 


When you use the Command Definition Utility to add a new command 

to your process command table or to the DCL command table, use the 
CLI$PRESENT and CLI$GET_VALUE routines in the program invoked by 
the new command. These routines retrieve information about the command 
string that invokes the program. 


When you use the Command Definition Utility to create an object module 
containing a command table and you link this module with a program, 
you must use all four CLI routines. First, use CLISDCL_PARSE and 
CLI$DISPATCH to parse command strings and invoke routines. Then, 
use CLI$PRESENT and CLI$GET_VALUE within the routines that execute 
each command. 





3.2 Example of Using the CLI Routines 


Example 3-1 contains a command definition file (GUBCOMMANDS.CLD) 
and a FORTRAN program (INCOME.FOR). INCOME.FOR uses the command 
definitions in SUBCOMMANDS.CLD to process commands. To execute the 
example, enter the following commands: 


$ SET COMMAND SUBCOMMANDS/OBJECT=SUBCOMMANDS 
$ FORTRAN INCOME 

$ LINK INCOME ,SUBCOMMANDS 

$ RUN INCOME 


INCOME.FOR accepts a command string and parses it using 
CLI$DCL_PARSE. If the command string is valid, the program uses 
CLI$DISPATCH to execute the command. Each routine uses CLISPRESENT 
and CLI$GET_VALUE to obtain information about the command string. 
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Example 3-1 Using the CLI Routines to Retrieve Information About 
Command Lines in a FORTRAN Program 


ge 2 2 2k fe 2 2g 2g 2 a fe A A 2 2 2 2 2 2 2K 2K 2K 2 fe 2 ok i 2 fe fe 2 2 2 2 2 2 2K 2 > 2K 2 2K 2k 2k 2K 2K 2K 2K 2K ok 


SUBCOMMANDS . CLD 
FAA GRICE I IG I AC IOI A ACA ACI I a a A CC 1 2 1 2K ak 


MODULE INCOME_SUBCOMMANDS 


DEFINE VERB ENTER 
ROUTINE ENTER 


DEFINE VERB FIX 
ROUTINE FIX 
QUALIFIER HOUSE_NUMBERS, VALUE (LIST) 


DEFINE VERB REPORT 

ROUTINE REPORT 

QUALIFIER OUTPUT, VALUE (TYPE = $FILE, 
DEFAULT = "INCOME. RPT") 
DEFAULT 


FEO SAKIC GG GOK I OIC A A kk 2k a 48 kak 
INCOME. FOR 

BAAS COOK OIC I CII #24 2 a 21 42k 

PROGRAM INCOME 

INTEGER STATUS, 

2 CLI$DCL_PARSE, 

2 CLI$DISPATCH 

INCLUDE '($RMSDEF) ' 

INCLUDE ' ($STSDEF) ' 

EXTERNAL INCOME_SUBCOMMANDS , 

2 LIB$GET_INPUT 


! Write explanatory text 

STATUS = LIB$PUT_OUTPUT 

2 ('Subcommands: ENTER - FIX - REPORT') 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) 

STATUS = LIB$PUT_OUTPUT 

2 ('Press CTRL/Z to exit') 

IF (.NOT. STATUS) CALL LIB$SIGNAL (Z%VAL (STATUS) ) 

! Get first subcommand 

STATUS = CLI$DCL_PARSE (%VAL (0), 
INCOME_SUBCOMMANDS , 
LIB$GET_INPUT, 
LIB$GET_INPUT, 
"INCOME> ') 

! Do it until user presses CTRL/Z 

DO WHILE (STATUS .NE. RMS$_EOF) 

! If no error on dcl_parse 

IF (STATUS) THEN 

! Dispatch depending on subcommand 

STATUS = CLI$DISPATCH () 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS) ) 

! Do not signal warning again 

ELSE IF (IBITS (STATUS, 0, 3) .NE. STS$K_WARNING) THEN 

CALL LIB$SIGNAL (%VAL (STATUS) ) 

END IF 


CLD module 
Parameter routine 
Command routine 
Command prompt 


DONN NY 
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Example 3—1 (Cont.) Using the CLI Routines to Retrieve Information 
About Command Lines in a FORTRAN 
Program 


! Get another subcommand 
STATUS = CLI$DCL_PARSE (%VAL (0), 


2 INCOME_SUBCOMMANDS, ! CLD module 

2 LIB$GET_INPUT, ! Parameter routine 
2 LIB$GET_INPUT, ! Command routine 

2 'INCOME> ') ! Command prompt 
END DO 

END 


INTEGER FUNCTION ENTER () 
INCLUDE '($SSDEF) ' 

TYPE *, 'ENTER invoked' 
ENTER = SS$_NORMAL 

END 


INTEGER FUNCTION FIX () 

INTEGER STATUS, 

2 CLI$PRESENT , 
“2 CLI$GET_VALUE 

CHARACTER*15 HOUSE_NUMBER 

INTEGER*2 HN_SIZE 

INCLUDE ' ($SSDEF)' 

EXTERNAL CLI$_ABSENT 

TYPE *, 'FIX invoked' 

! If user types /house_numbers=(n,...) 
IF (CLI$PRESENT ('HOUSE_NUMBERS')) THEN 
! Get first value for /house_numbers 
STATUS = CLI$GET_VALUE ('HOUSE_NUMBERS', 
2 HOUSE_NUMBER,, 
2 HN_SIZE) 

! Do it until the list is depleted 

DO WHILE (STATUS) 


TYPE *, 'House number = ', HOUSE_NUMBER (1:HN_SIZE) 
STATUS = CLI$GET_VALUE ('HOUSE_NUMBERS' , 

2 HOUSE_NUMBER, 

2 HN_SIZE) 

END DO 


! Make sure termination status was correct 
IF (STATUS .NE. %LOC (CLI$_ABSENT)) THEN 
CALL LIB$SIGNAL (%VAL (STATUS) ) 

END IF 

END IF 

FIX = SS$_NORMAL 

END 


INTEGER FUNCTION REPORT () 
INTEGER STATUS, 

2 CLI$GET_VALUE 
CHARACTER*64 FILENAME 
INTEGER*2 FN_SIZE 
INCLUDE '($SSDEF) ' 

TYPE *, 'REPORT entered! 


Example 3—1 Cont'd. on next page 
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Example 3—1 (Cont.) Using the CLI Routines to Retrieve Information 
About Command Lines in a FORTRAN 
Program 


! Get value for /output 

STATUS = CLI$GET_VALUE ('OUTPUT', 

2 FILENAME, 

2 FN_SIZE) ; 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS) ) 
TYPE *, 'Output file: ', FILENAME (1:FN_SIZE) 
REPORT = SS$_NORMAL 

END 





3.3 CLI Routines 


The following pages describe the individual CLI routines. 


CLI-—4 


Command Language (CLI) Routines 
CLISDCL_PARSE 


CLISDCL_PARSE Parse DCL Command String 


The CLISDCL_PARSE routine supplies a command string to DCL for 
parsing. DCL separates the command string into its individual elements 
according to the syntax specified in the command table. 





FORMAT ~CLISDCL_PARSE [command_string] ,table 
[,param_routine] [, prompt_routine] 
[,prompt_string] 





RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS command_string 
_ VMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor—fixed length 


Character string containing the command to be parsed. The command 
string argument is the address of a descriptor specifying the command string 
to be parsed. If the command string includes a comment (delimited by an 
exclamation mark), DCL ignores the comment. 


If the command string contains a hyphen to indicate that the string is being 
continued, DCL uses the routine specified in the prompt_routine argument 
to obtain the rest of the string. The command string is limited to 256 
characters. However, if the string is continued with a hyphen, CLI$DCL_— » 
PARSE can prompt for additional input until the total number of characters is 
1024. 


If you specify the command_string argument as zero and specify a prompt 
routine, then DCL prompts for the entire command string. However, if you 
specify the command_string argument as zero and also specify the prompt— 
routine argument as zero, then DCL restores the parse state of the command 
string that originally invoked the image. 


CLI$DCL—PARSE does not perform DCL-style symbol substitution on the 
command string. 
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table 

VMS usage: char_string 
type: unspecified 
access: read only 


mechanism: by reference 


Name of the module containing the command language description. The 
table argument is the address of the command table that describes the syntax 
by which the command line should be parsed. This is usually represented by 
a global symbol that is created by the Command Definition Utility when it 
processes the MODULE statement in the command definition file. 


The command table is created with the DCL command SET COMMAND 
/OBJECT and is linked with your image. 


param_routine 


VMS usage: procedure 

type: procedure entry mask 
access: read only 

mechanism: by reference 


Name of a routine to obtain a required parameter not supplied in the 
command text. The param_routine argument is the address of a routine 
containing a required parameter that was not specified in the command_ 
string argument. 


To specify the parameter routine, use the address of LIB6GET_INPUT or the 
address of a routine of your own that has the same three-argument calling 
format as LIB${GET_INPUT. See the description of LIB$}GET_INPUT in the 
VMS RTL Library (LIB$) Manual for information about the calling format. The 
status returned by LIB6GET_INPUT must be success or the 
CLI$DCL_PARSE routine exits and propagates the error outward. 


You can obtain the prompt string for a required parameter from the command 
table specified in the table argument. 


prompt_routine 

VMS usage: procedure 

type: procedure entry mask 
access: read only 


mechanism: by reference 


Name of a routine to obtain all or part of the text of a command. The 
prompt_routine argument is the address of a routine to obtain the text or 
the remaining text of the command depending on the command_string 
argument. If you specify a zero in the command_string argument, DCL 
uses this routine to obtain an entire command line. DCL uses this routine to 
obtain a continued command line if the command string (obtained from the 
command_string argument) contains a hyphen to indicate that the string is 
being continued. 


To specify the prompt routine, use the address of LIB}GET_INPUT or the 
address of a routine of your own that has the same three-argument calling 
format as LIB${}GET_INPUT. See the description of LIB$}GET_INPUT in the 
VMS RTL Library (LIB$) Manual for information about the calling format. The 
status returned by LIB6GET_INPUT must be success or the 
CLI$DCL_PARSE routine exits and propagates the error outward. 
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prompt_string 

VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor 


Character string containing a prompt. The prompt—string argument is the 
address of a string descriptor pointing to the prompt string to be passed as 
the second argument to the prompt—routine argument. 


If DCL is using the prompt routine to obtain a continuation line, DCL inserts 
an underscore character before the first character of the prompt string to 
create the continuation prompt. If DCL is using the prompt routine to obtain 
an entire command line (that is, a zero was specified as the command_string 
argument), DCL uses the prompt string exactly as specified. 


The prompt string is limited to 32 characters. The string COMMAND is the 
default prompt string. 





DESCRIPTION 


The CLI$DCL_—PARSE routine supplies a command string to DCL for parsing. 
DCL parses the command string according to the syntax in the command table 
specified in the table argument. 


The CLI$DCL—PARSE routine can prompt for required parameters if you 
specify a parameter routine in the routine call. In addition, the | 
CLI$DCL_PARSE routine can prompt for entire or continued command lines 
if you supply the address of a prompt routine. 


If you press CTRL/Z or if you return RMS$_EOF as a response to any 
prompt, CLISDCL_PARSE immediately terminates and returns the status — 
RMS$_EOF. If you enter a null string in response to a prompt for an entire or 
a continued command string (specified with the prompt—routine argument), 
CLI$DCL_PARSE terminates and returns the status CLIS_NOCOMD. If 
you enter a null string in response to a prompt for a required parameter, 
CLI$DCL_PARSE displays the prompt. 


Whenever CLI$DCL_—PARSE encounters an error, it both signals and returns 
the error. 





CONDITION 
VALUES 
RETURNED 


CLI$_NORMAL Normal successful completion. 


CLI$_.NOCOMD Routine terminated. You entered a null string in 
response to a prompt from the prompt_—routine 
argument, causing the CLISDCL_PARSE routine to 
terminate. 


RMS$_EOF Routine terminated. You pressed CTRL/Z in 
response to a prompt, causing the 
CLIS$DCL_PARSE routine to terminate. 
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CLISDISPATCH Dispatch to Action Routine 


The CLISDISPATCH routine invokes the subroutine associated with the 
verb most recently parsed by a CLISDCL_PARSE routine call. 

















FORMAT CLISDISPATCH [userarg] 

RETURNS VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value . 
Longword condition value. Most utility routines return a condition value 
in RO. The condition value that this routine can return is listed under 
CONDITION VALUE RETURNED. 

ARGUMENT _ userarg . 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by value 

Data to be passed to the action routine. The userarg argument is a longword 
that contains the data to be passed to the action routine. This data can be 
used in any way you want. 

DESCRIPTION _ The CLI$DISPATCH routine invokes the subroutine associated with the verb 
most recently parsed by a CLIS;DCL—PARSE routine call. If the routine is 
successfully invoked, the return status is the status returned by the action 
routine. Otherwise, a status of CLI$_INVROUT is returned. 

CONDITION | | 

VALUE CLI$_INVROUT CLISDISPATCH unable to invoke the routine. An 

invalid routine is specified in the command table, 

RETURNED or no routine is specified. 
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CLISGET_VALUE Get Value of Entity in 


Command String 


The CLISGET_VALUE routine retrieves a value associated with a specified 
qualifier, parameter, keyword, or keyword path from the parsed command 
string. 





FORMAT 


CLISGET_VALUE entity_desc ,retdesc [,retlength] 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


entity_desc 

VMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Character string containing the label (or name if no label is defined) of the 
entity. The entity_desc argument is the address of a string descriptor that 
points to an entity that may appear on a command line. The entity_desc 
argument can be expressed as one of the following: 


e A parameter, qualifier, or keyword name or label 


e A keyword path 


The entity_desc argument can contain qualifier, parameter, or keyword 
names, or can contain labels that were assigned with the LABEL clause in the 
command definition file. If you used the LABEL clause to assign a label to an 
entity, you must specify the label in the entity_desc argument. Otherwise, 
use the name of the entity. 


You use a keyword path to reference keywords used as values of parameters, 
qualifiers, or other keywords. A keyword path contains a list of entity names 
or labels separated by periods. If the LABEL clause was used to assign a label 
to an entity, you must specify the label in the keyword path. Otherwise, you 
must use the name of the entity. 


The following command string illustrates a situation where keyword paths 
are needed to uniquely identify keywords. In this command string, you can 
use the same keywords with more than one qualifier. (This is defined in the 
command definition file by having two qualifiers refer to the same DEFINE 
TYPE statement.) 


$ NEWCOMMAND/QUAL1=(START=5, END=10) /QUAL2=(START=2 , END=5) 
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The keyword path QUAL1.START identifies the START keyword when 

it is used with QUALI; the keyword path QUAL2.START identifies the 
keyword START when it is used with QUAL2. Because the name START is 
an ambiguous reference if used alone, the keywords QUALI and QUAL2 are 
needed to resolve the ambiguity. 


You can omit keywords from the beginning of a keyword path if they are not 
needed to unambiguously resolve a keyword reference. ‘A keyword path can 
be no more than eight names long. 


If you use an ambiguous keyword reference, DCL resolves the reference by 
checking, in the following order: 


1 The parameters in your command definition file, in the order they are 
listed 


2 The qualifiers in your command definition file, in the order they are listed 


3 The keyword paths for each parameter, in the order the parameters are 
listed 


4 The keyword paths for each qualifier, in the order the qualifiers are listed 


DCL uses the first occurrence of the entity as the keyword path. Note that 
DCL does not issue an error message if you provide an ambiguous keyword. 
However, because the keyword search order may change in future releases of 
VMS, you should never use ambiguous keyword references. 


If the entity_desc argument does not exist in the command table, 
CLI$GET_VALUE signals a syntax error (by means of the signaling 
mechanism described in the VMS Run-Time Library Routines Volume). 


retdesc 

VMS usage: char_string 
type: character string 
access: write only 


mechanism: by descriptor 


Character string containing the value retrieved by CLISGET_VALUE. The 
retdesc argument is the address of a string descriptor pointing to the buffer to 
receive the string value retrieved by CLISGET_VALUE. The string is returned 
using the STR6¢COPY_DX VAX-11 Run-Time Library routine. 


If there are errors in the specification of the return descriptor or in copying 

the results using that descriptor, the STR$COPY_DxX routine will signal the 
errors. For a list of these errors, see the VMS RTL String Manipulation (STR$) 
Manual. 


retlength | 
VMS usage: word_unsigned 

type: word (unsigned) 
access: write only 


mechanism: by reference 


Word containing the number of characters DCL returns to retdesc. The 
retlength argument is the address of the word containing the length of the 
retrieved value. 


Command Language (CLI) Routines 
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DESCRIPTION 


The CLI$GET_VALUE routine retrieves a value associated with a specified 
qualifier, parameter, keyword, or keyword path from the parsed command 
string. 


You can use the following label names with CLISGET_VALUE to retrieve 
special strings: 


$VERB Describes the verb in the command string (the first four letters of the 
spelling as defined in the command table, instead of the string that 
was actually typed). 


$LINE Describes the entire command string as stored internally by DCL. In 
the internal representation of the command string, multiple spaces and 
tabs are removed, alphabetic characters are converted to uppercase, 
and comments are stripped. Integers are converted to decimal. If 
dates and times are specified in the command string, DCL fills in any 
defaulted fields. Also, if date-time strings (such as YESTERDAY) are 
used, DCL substitutes the corresponding absolute time value. 


To obtain the values for a list of entities, call CLISGET_VALUE repeatedly 
until all values have been returned. After each CLISGET_VALUE call, the 


- returned condition value indicates whether there are more values to be 


obtained. You should call CLISGET_VALUE until you receive a condition 
value of CLIS_ABSENT. 


When you are using CLISGET_VALUE to obtain a list of qualifier or keyword 
values, you should get all values in the list before starting to parse the next 
entity. 





CONDITION 
VALUES 
RETURNED 


CLI$_COMMA Returned value terminated by a comma. This 
shows there are additional values in the list. 

CLI$_CONCAT Returned value concatenated to the next value with 
a plus sign. This shows there are additional values 
in the list. 

SS$_NORMAL Returned value terminated by a blank or an end-of- 


line. This shows that the value is the last, or only, 
value in the list. 


CLIS_ABSENT No value returned. The value is not present, or the 
last value in the list was already returned. 
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CLISPRESENT Determine Presence of Entity in 
Command String 


The CLISPRESENT routine examines the parsed command string to 
determine whether the entity referred to by the entity_desc argument 








is present. 
FORMAT CLISPRESENT entity_desc 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENT entity_desc 
VMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Character string containing the label (or name if no label is defined) of the 
entity. The entity_desc argument is the address of a string descriptor that 
points to an entity that may appear on a command line. An entity can be 
expressed as one of the following: 


e¢ A parameter, qualifier, or keyword name or label 


e A keyword path 


A keyword path is used to reference keywords that are accepted by 
parameters, qualifiers, or other keywords. A keyword path contains a list 
of entity names separated by periods. See the description of the entity_ 
desc argument in the CLISGET_VALUE routine for more information about 
specifying keyword paths as arguments for CLI routines. 


The entity_desc argument can contain parameter, qualifier, or keyword 
names, or can contain labels that were assigned with the LABEL clause in the 
command definition file. If the LABEL clause was used to assign a label to 

a qualifier, parameter, or keyword, you must specify the label in the entity_ 
desc argument. Otherwise, you must use the actual name of the qualifier, 
parameter, or keyword. 


If the entity_desc argument does not exist in the command table, 
CLI$PRESENT signals a syntax error (by means of the signaling mechanism 
described in the VMS Run-Time Library Routines Volume). 
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DESCRIPTION 


The CLI$PRESENT routine examines the parsed command string to determine 
whether the entity referred to by the entity_desc argument is present. 


When CLI$PRESENT tests whether a qualifier is present, the condition 
value indicates whether the qualifier is used globally or locally. You can 

use a global qualifier anywhere in the command line; you use a local 
qualifier only after a parameter. A global qualifier is defined in the command 
definition file with PLACEMENT=GLOBAL,; a local qualifier is defined with 


_ PLACEMENT=LOCAL. 


When you test for the presence of a global qualifier, CLISPRESENT 
determines if the qualifier is present anywhere in the command string. If 

the qualifier is present in its positive form, CLIS5PRESENT returns 
CLI$_PRESENT,; if the qualifier is present in its negative form, CLISPRESENT 
returns CLI$_.NEGATED. 


You can test for the presence of a local qualifier when you are parsing 
parameters that can be followed by qualifiers. After you call 
CLI$GET_VALUE to fetch the parameter value, call CLISPRESENT to 
determine whether the local qualifier is present. If the local qualifier is 
present in its positive form, CLIS5PRESENT returns CLI$_LOCPRES,; if the 
local qualifier is present in its negative form, CLISPRESENT returns 
CLI$6_LOCNEG. 


A positional qualifier affects the entire command line if it appears after the 
verb but before the first parameter. A positional qualifier affects a single 
parameter if it appears after a parameter. A positional qualifier is defined in 
the command definition file with the PLACEMENT=POSITIONAL clause. 


To determine whether a positional qualifier is used globally, call 
CLI$PRESENT to test for the qualifier before you call CLISGET_VALUE 
to fetch any parameter values. If the positional qualifier is used globally, 
CLI$PRESENT returns either CLI$5_PRESENT or CLI$_NEGATED. 


To determine whether a positional qualifier is used locally, call CLIS PRESENT 
immediately after a parameter value has been fetched by CLISGET_VALUE. 
The most recent CLISGET_VALUE call to fetch a parameter defines the 
context for a qualifier search. Therefore, CLISPRESENT tests whether a 
positional qualifier was specified after the parameter that was fetched by the 
most recent CLISGET_VALUE call. If the positional qualifier is used locally, 
CLI$PRESENT returns either CLIS_LOCPRES or CLI$_LOCNEG. 
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CLISPRESENT 





CONDITION 
VALUES CLI$_PRESENT 
RETURNED 


CLI$_NEGATED 
CLI$__LOCPRES 
CLI$__LOCNEG 
CLI$__DEFAULTED 


CLIS_ABSENT 
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Specified entity present in the command string. 
This status is returned for all entities except local 
qualifiers and positional qualifiers that are used 
locally. 


Specified qualifier present in negated form (with 
/NO) and used as a global qualifier. 


Specified qualifier present and used as a local 
qualifier. 


Specified qualifier present in negated form (with 
/NO) and used as a local qualifier. 


Specified entity not present, but there is a default 
value. 


Specified entity not present, and there is no default 
value. 


7A Convert (CONV) Routines 





4.1 Introduction to Convert Routines 


This chapter describes the Convert routines. These routines perform the 
functions of both the VMS RMS Convert and Convert/Reclaim Utilities. 


The Convert Utility copies records from one or more files to an output file, 
changing the record format and file organization to that of the output file. 
You can invoke the functions of the Convert Utility from within a program by 
calling the following series of three routines, in this order: 


1 CONV$PASS_FILES 
2 CONV$PASS_OPTIONS 
3 CONV$CONVERT 


The Convert/Reclaim Utility reclaims empty buckets in Prolog 3 indexed 
files so that new records can be written in them. You can invoke the 
functions of the Convert/Reclaim Utility from within a program by calling 
the CONV$RECLAIM routine. 


These routines cannot be called from AST level. 





4.2 Examples of Using the Convert Routines 


Example 4-1 shows how to use the Convert routines in a FORTRAN 
program. 


Example 4—1 Using the Convert Routines in a FORTRAN Program 


This program calls the routines that perform the 
functions of the Convert Utility. It creates an 
indexed output file named CUSTDATA.DAT from the 

specifications in an FDL file named INDEXED.FDL. 
The program then loads CUSTDATA.DAT with records 
from the sequential file SEQ.DAT. No exception 

file is created. This program also returns all 

the CONVERT statistics. 


* *¥ *¥ eH He He 


* 


Program declarations 
IMPLICIT INTEGER*4 (A - Z) 


Set up parameter list: number of options, CREATE, 
NOSHARE, FAST_LOAD, MERGE, APPEND, SORT, WORK_FILES, 
KEY=0, NOPAD, PAD CHARACTER, NOTRUNCATE, 

NOEXIT, NOFIXED_CONTROL, FILL_BUCKETS, NOREAD_CHECK, 
NOWRITE_CHECK, FDL, and NOEXCEPTION. 


* ee e * * 


INTEGER*4 OPTIONS (19) 
1 /18,1,0,1,0,0,1,2,0,0,0,0,0,0,0,0,0,1,0/ 


Example 4—1 Cont'd. on next page 
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4.2 Examples of Using the Convert Routines 


Example 4—1 (Cont.) Using the Convert Routines in a FORTRAN 


Program 
* Set up statistics list. Pass an array with the 
= number of statistics that you want. There are four 
* ~-- number of files, number of records, exception 
* records, and good records, in that order. 
INTEGER*4 STATSBLK(5) /4,0,0,0,0/ 
* Declare the file names. 
CHARACTER IN_FILE*7. /'SEQ.DAT'/, 
1 OUT_FILE*12 /'CUSTDATA.DAT'/, 
1 FDL_FILE*11 /'INDEXED.FDL'/ 
* Call the routines in their required order. 
STATUS = CONV$PASS_FILES (IN_FILE, OUT_FILE, FDL_FILE) 
IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS) ) 
STATUS = CONV$PASS_OPTIONS (OPTIONS) 
IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS) ) 
STATUS = CONV$CONVERT (STATSBLK) 
IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS) ) 
* Display the statistics information. 


WRITE (6,1000) (STATSBLK(I) ,I=2,5) 
1000 FORMAT (1X,'Number of files processed: ',I15/, 


| 1X,'Number of records: ',15/, 

1 1X,'Number of exception records: ',I5/, 
1 1X, 'Number of valid records: ',I5) 

END 


Example 4-2 shows how to use the Convert routines in a MACRO program. 


Example 4—2 Using the Convert Routines ina MACRO Program 


.TITLE CONVSTAT.MAR 


; This module calls the routines that perform the functions 

; of the Convert Utility. It creates an indexed output file 
; named CUSTDATA.DAT from the specifications in an FDL file 

; named INDEXED.FDL, and loads CUSTDATA.DAT with records from 
; the sequential file SEQ.DAT. No exception file is created. 
; This module also returns all the CONVERT statistics. 


; Declare the file names. 


FILEIN: .ASCID /SEQ.DAT/ 
FILEOUT: . ASCID /CUSTDATA.DAT/ 
FDLFILE: . ASCID / INDEXED . FDL/ 


Example 4—2 Cont'd. on next page 
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4.2 Examples of Using the Convert Routines 


Example 4—2 (Cont.) Using the Convert Routines in a MACRO 
Program 


, 


Set up parameter list. 


PARAM_LIST: .LONG 1 


8 ;NUMBER OF LONGWORDS FOLLOWING 
-LONG 1 ; CREATE 
.LONG 0 ; NOSHARE 
-LONG 1 ; FAST_LOAD 
._LONG 0 ; MERGE 
-LONG 0O ; APPEND 
-LONG 1 ; SORT 
-~LONG 2 ;WORK_FILES 
.LONG 0 ; KEY=0 
-_LONG O ; NOPAD 
-LONG 0O ;PAD CHARACTER 
-_LONG O ; NOTRUNCATE 
-LONG 0 ; NOEXIT 
.LONG 0 ; NOFIXED_CONTROL 
.LONG 0 ; FILL_BUCKETS 
.LONG 0 ; NOREAD_CHECK 
.LONG 0 ; NOWRITE_CHECK 
-LONG 1 ;FDL 
._LONG 0 ; NOEXCEPTION 


; Have to use Formatted ASCII Output (FAO) conversion 
; Declare FAQ info for statistics 


FAO_DESC : . LONG 132 


. LONG FAO_BUFFER 
FAO_BUFFER: . BLKB 132 
FAO_LEN: . BLKL 1 
OUTSTUFF : .ASCID #Number of files processed: !UL !/- 


Number of records: !UL !/- 
Number of exception records: !UL !/- 
Number of valid records: !UL !/# 


; Have to pass a longword to the CONV$CONVERT ROUTINE with the 
; number of statistics that we want. There are 4 -- number of 
; files, number of records, exception records, good records, 

; in that order. 


STATSBLK : -LONG 4 ;The value 4 is the number of statistics 
;that we want. we pass this value to 
;the END_CONVERT routine. 

STATS: -BLKL 4 ;Where we place the statistics. This block 
;must follow the longword that tells how 
;many stats we want. 

TIMES : .BLKL 5 ;Where we place the timing info. 


Declare the external routines. 


.EXTRN CONV$PASS_FILES , CONV$PASS_OPTIONS , CONV$CONVERT, - 
LIB$PUT_OUTPUT , LIB$INIT_TIMER, LIB$SYS_FAOL 


-ENTRY CONV, “M<R2,R3,R4,R5,R6,R7> ;SAVE THOSE REGISTERS ; 


Example 4—2 Cont'd. on next page 
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4.2 Examples of Using the Convert Routines 


Example 4—2 (Cont.) Using the Convert Routines ina MACRO 
Program 


; Perform operations. Push addresses on arg stack, call routines. 


PUSHAL TIMES 
CALLS #1,G°LIBSINIT_TIMER ;Start the timer 


PUSHAL FDLFILE 

PUSHAL FILEOUT 

PUSHAL FILEIN ;Push filenames on arg stack 
CALLS #3,G°CONV$PASS_FILES ;Pass filenames 

BLBC RO, 10$ 


PUSHAL PARAM_LIST ;Push parameter list 
CALLS #1,G°CONV$PASS_OPTIONS ;Make the second call 
BLBC RO, 10$ 


PUSHAL STATSBLK ;Push address of the number of 
;Statistics 
CALLS #1 ,G°CONV$CONVERT ;Perform conversion 


BLBC RO, 10$ 


; Now need an FAO routine to format the counts 


$FAOL_S CTRSTR=OUTSTUFF , OUTLEN=FAO_LEN , OUTBUF=FAO_DESC, - 
PRMLST=STATS 
BLBC RO, 10$ 


PUSHAL FAO_DESC ;Push output buffer on stack 
CALLS #1,G°LIB$PUT_OUTPUT ;Send the output buffer to 
; SYS$OUTPUT 


BLBC RO, 10$ 
; Display times 
PUSHAL TIMES 
CALLS #1,G°LIB$SHOW_TIMER 
BLBC RO, 10$ 
MOVL #SS$_NORMAL, RO 
10$: RET 


. END CONV 
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4.2 Examples of Using the Convert Routines 


Example 4-3 shows how to use the CONV$RECLAIM routine in a FORTRAN 
program. 


Example 4—3 Using the CONV$RECLAIM Routine in a FORTRAN 
Program 





This program calls the routine that performs the 
function of the Convert/Reclaim Utility. It 
reclaims empty buckets from an indexed file named 
PROL3.DAT. It also returns all the CONVERT/RECLAIM 
statistics. 

Program declarations 


IMPLICIT INTEGER*4 (A - Z) 


%*¥ * ¥ %¥ ¥ * 


Set up a statistics block. There are four --- data 
* buckets scanned, data buckets reclaimed, index 
* buckets reclaimed, total buckets reclaimed. 


INTEGER*4 QUTSTATS(5) /4,0,0,0,0/ 
* Declare the input file. 

CHARACTER IN_FILE*9 /'PROL3.DAT'/ 
* Call the routine. 


STATUS = CONV$RECLAIM (IN_FILE, OUTSTATS) 
IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS) ) 


* Display the statistics. 


WRITE (6,1000) (OUTSTATS(I) ,I=2,5) 
1000 FORMAT (1X,'Number of data buckets scanned: ',I5/, 


1 1X,'Number of data buckets reclaimed: ',I5/, 
1 1X,'Number of index buckets reclaimed: ',I5/, 
1 1X,'Total buckets reclaimed: ',I5) 

END 
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Example 4-4 shows how to use the CONV$RECLAIM routine in a MACR 
program. = 


Example 4-4 Using the CONV$RECLAIM Routine in a MACRO 
Program 





. TITLE CONVREC.MAR 


; This module calls the routine that performs the 
; function of the CONVERT/RECLAIM Utility. It reclaims 
; empty buckets from an indexed file named PROL3.DAT. 


; This module also returns all of the CONVERT/RECLAIM 
; statistics. 


; Declare the file name. 


FILEIN: .ASCID /PROL3.DAT/ 


; Declare statistics blocks 


OUTSTATS: .LONG 4 
._BLKL 4 
; Declare FAO info for statistics 


. 
? 


FAO_DESC: LONG 132 


. LONG FAO_BUFFER 
FAO_BUFFER: . BLKB 132 
_FAQ_LEN: . BLKL 1 
OQUTSTUFF : .ASCID #Data buckets scanned: !UL !/- 


Data buckets~reclaimed: !UL !/- 
Index buckets reclaimed: !UL !/- 
Total buckets reclaimed: !UL !/# 


Looking for four statistics back from the end call. 
Use FAO conversion. 


; Declare the external routines. 
.EXTRN CONV$RECLAIM, LIB$PUT_OUTPUT 
-ENTRY CONV, “M<> 


Perform operations. Push addresses on arg stack, call 
routines. 


we wee we we we 


PUSHAL OUTSTATS 

PUSHAL FILEIN ;PUSH FILENAME ON ARG STACK 
CALLS #2,G°CONV$RECLAIM ;PASS FILENAME 

BLBC RO, 10$ 
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Example 4—4 (Cont.) Using the CONV$RECLAIM Routine in a 
MACRO Program 


; Now need an FAO routine to format the counts. 
$FAOL_S CTRSTR=OUTSTUFF , OUTLEN=FAO_LEN , OUTBUF=FAO_DESC, - 
PRMLST=OUTSTATS+4 
BLBC RO, 10$ 


PUSHAL FAO_DESC ;PUSH OUTPUT BUFFER ON STACK 
CALLS #1, G°LIB$PUT_OUTPUT ;SEND THE OUTPUT BUFFER TO 
; SYS$OUTPUT 


BLBC RO, 10$ 
MOVL #SS$_NORMAL , RO 
10$: RET 


.END CONV 





4.3 Convert Routines 


The following pages describe the individual Convert routines. 
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CONV$CONVERT Initiate Conversion 


The CONV$CONVERT routine uses the Convert Utility to perform 
the actual conversion begun with CONV$PASS_FILES and 
CONV$PASS_OPTIONS. Optionally, the routine can return statistics 
about the conversion. 








FORMAT CONVSCONVERT [status_block_address] [, flags] 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS __ status_block_address 
VMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


The conversion statistics. The status_block—address argument is the address 
of a variable-length array of longwords that receives statistics about the 
conversion. The format of the array is as follows: 


number of statistics 

number of files 

number of records 

number of exception records 
number of valid records 


flags 

VMS usage: mask_longword 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Flags (or masks) that control how the fdl_filespec argument is interpreted 
and how errors are signalled. The flags argument is the address of a 
longword containing control flags (or a mask). If you omit the flags argument 
or specify it as zero, no flags are set. The flags and their meanings are 
described in the following table. 
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Flag 
CONV$V_FDL—STRING 


CONV$V_SIGNAL 
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CONV$CONVERT 


Function 


Interprets the fdl_filespec argument supplied in the 

call to CONV$PASS_FILES as an FDL specification in 
string form. By default, this argument is interpreted 

as a file name of an FDL file. 


Signals any error. By default, the status code is 
returned to the calling image. 


This argument is optional. By default, an error status is returned rather than 





signalled. 
CONDITION | 
VALUES SS$_NORMAL Normal successful completion. 
RETURNED CONV$_BADBLK Invalid option block. 


CONV$_BADLOGIC 
CONV$_BADSORT 
CONV$_CLOSEIN 
CONV$_CLOSEOUT 
CONV$_CONFQUAL 
CONV$_CREA_ERR 
CONV$_CREATEDSTM 


CONV$_DELPRI 
CONV$_DUP 
CONV$_EXTN_ERR 
CONV$_FATALEXC 
CONV$_FILLIM 
CONV$_IDX _LIM 
CONV$_ILL_KEY 
CONV$_INP_FILES 
CONV$_INSVIRMEM 
CONV$_KEY 
CONV$_LOADIDX 
CONV$_NARG 
CONV$_NOKEY 
CONV$_NOTIDX 
CONV$_NOTSEQ 
CONV$_NOWILD 
CONV$_OPENEXC 
CONV$_OPENIN 
CONV$_OPENOUT 
CONV$_ORDER 


Internal logic error detected. 

Error trying to sort input file. 

Error closing file specification as input. 
Error closing file specification as output. 
Conflicting qualifiers. 

Error creating output file. 


File specification has been created in stream 
format. 


Cannot delete primary key. 

Duplicate key encountered. 

Unable to extend output file. 

Fatal exception encountered. 

Exceeded open file limit. 

Exceeded maximum index level. 

Illegal key or value out of range. 

Too many input files. 

Insufficient virtual memory. 

Invalid record key. 

Error loading secondary index n. 

Wrong number of arguments. 

No such key. 

File is not an indexed file. 

Output file is not a sequential file. 

No wildcard permitted. 

Error opening exception file specification. 
Error opening file specification as input. 
Error opening file specification as output. 
Routine called out of order. 
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CONV$_PAD 


CONV$_PROERR 
CONV$_PROL_WRT 
CONV$_READERR 
CONV$_REX 
CONV$_RMS 
CONV$_RSK 
CONV$_RSZ 
CONV$_RTL 
CONV$_RTS 
CONV$_SEQ 
CONV$_UDF_BKS 
CONV$_UDF_BLK 
CONV$_VALERR 
CONV$_VFC 
CONV$_WRITEERR 


CONV-10 


PAD option ignored; output record format not 
fixed. 


Error reading prolog. 

Prolog write error. 

Error reading file specification. 

Record already exists. | 

Record caused RMS severe error. 

Record shorter than primary key. 

Record does not fit in block/bucket. 

Record longer than maximum record length. 
Record too short for fixed record format file. 
Record not in order. 

Cannot convert UDF records into spanned file. 
Cannot fit UDF records into single block bucket. 
Specified value is out of legal range. 

Record too short to fill fixed part of VFC record. 


Error writing file specification. 
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CONVS$PASS_FILES Specify Conversion Files 


The CONV$PASS_FILES routine specifies a file to be converted using the 
CONVS$CONVERT routine. 





FORMAT CONV$PASS_FILES input_filespec ,output_filespec 
[_fdl_filespec] 
[,exception_filespec] 





[flags] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS __ input_filespec 
VMS usage: char_string 
type: character-coded text string 
access: read only 
mechanism: by descriptor—fixed-length string descriptor 


The name of the file to be converted. The input_filespec argument is the 
address of a string descriptor pointing to the name of the file to be converted. 


output_filespec 

VMS usage: char_string 

type: character-coded text string 

access: read only 

mechanism: by descriptor—fixed-length string descriptor 


The name of the file that receives the records from the input file. The 
output_filespec argument is the address of a string descriptor pointing to the 
name of the file that receives the records from the input file. 


fdl_filespec 

VMS usage: char_string 

type: character-coded text string 

access: read only . 

mechanism: by descriptor—fixed-length string descriptor 


The name of the FDL file that defines the output file. The fdl_filespec 
argument is the address of a string descriptor pointing to the name of the 
FDL file. 
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exception_filespec 


VMS usage: char_string 

type: character-coded text string 

access: _ read only 

mechanism: by descriptor—fixed-length string descriptor 


The name of the file that receives copies of records that cannot be written to 
the output file. The exception—filespec argument is the address of a string 
descriptor pointing to this name. 


flags 

VMS usage: mask_longword 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Flags (or masks) that control how the fdl_filespec argument is interpreted 
and how errors are signalled. The flags argument is the address of a 
longword containing the control flags (or mask). If you omit this argument 
or specify it as zero, no flags are set. If you specify a flag, it remains in effect 
until you explicitly reset it in a subsequent call to a Convert routine. 


The flags and their meanings are described in the following table. 


Flag Function 


CONV$V_FDL_STRING Interprets the fdl_filespec argument as an FDL 
specification in string form. By default, this argument 
is interpreted as a file name of an FDL file. 

CONV$V_SIGNAL Signals any error. By default, the status code is 
returned to the calling image. 


This argument is optional. By default, an error status is returned rather than 
signalled. 





DESCRIPTION 
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_ The CONV$PASS_FILES routine specifies a file to be converted using the 


CONV$CONVERT routine. A single call to CONV$PASS_FILES allows you 
to specify an input file, an output file, an FDL file, and an exception file. If 
you have multiple input files, you must call CONV$PASS_FILES once for 
each file. You need to specify only the input_filespec argument for the 
additional files, as follows: 


status = CONV$PASS_FILES (input_filespec) 


The additional calls must immediately follow the original call that specified 
the output file specification. You may specify as many as 9 additional files for 
a maximum total of 10. 


Wildcard characters are not allowed in the file specifications passed to the 
Convert routines. 
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CONDITION | 

VALUES SS$_NORMAL Normal sea completion. 

RETURNED CONV$_INP_FILES Too many input files. 
CONV$_INSVIRMEM Insufficient virtual memory. 
CONV$_NARG Wrong number of arguments. 
CONV$_ORDER Routine called out of order. 
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CONV$PASS_OPTIONS Specify Processing 
Options 


The CONV$PASS_OPTIONS routine specifies which qualifiers are to be 
used by the Convert Utility (CONVERT). 








FORMAT CONV$PASS_OPTIONS [parameter_list_address] 
[flags] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS _ parameter_list_address 
VMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Parameter list specifying information about the CONVERT qualifiers. The 

parameter_list_address argument is the address of a variable-length array 
of longwords. The first longword in the array is the number of parameters 
in the array. Each subsequent longword in the array (from the second one 
on) is associated with one of the CONVERT qualifiers. These functions are 
described in the VMS Convert and Convert /Reclaim Utility Manual. 


To set one of the CONVERT qualifiers, you place a 1 in the longword 
associated with that qualifier. If you do not want to set one of the qualifiers 
(which has the same effect as using the negative form of the qualifier on the 
CONVERT command), you place a 0 in the correct longword. 


If you do not specify parameter_list_address, then the following default 
values apply. You can also take all default values by passing the address of a 
longword that contains 0, which means a parameter list of 0 longwords. 


If you have specified all the values you want set, you may want to take the 
default values for all subsequent qualifiers in the list. You may omit the 
subsequent ones if you give the array length in the first longword. This is 
why the first longword contains a count of the qualifiers. 


The qualifiers must appear in the following order. 
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Default Value (in 


CONVSPASS_OPTIONS 


Qualifier Longwords) Default CONVERT Value 
CREATE 1 /CREATE 

SHARE O /NOSHARE 

FAST_LOAD 1 /FAST_LOAD 

MERGE 0 /NOMERGE 

APPEND 0 /NOAPPEND 

SORT 1 /SORT 

WORK _FILES Z /WORK_FILES=2 

KEY 0 /KEY=0 

PAD 0) /NOPAD 

Pad character 0 Pad character=O 
TRUNCATE 6) /NOTRUNCATE 

EXIT O /NOEXIT 
FIXED_CONTROL 0 /NOFIXED_CONTROL 
FILL_BUCKETS 0 /NOFILL__BUCKETS 
READ_CHECK 0 /NOREAD_CHECK 
WRITE_CHECK 0. /NOWRITE_CHECK 

FDL O /NOFDL 

EXCEPTION 0) /NOEXCEPTION 

PROLOG No default System or process default 


If you want to use the default null character for the PAD qualifier, you should 
specify 0 in the pad character longword. You can also specify the default null 
character by omitting the pad character longword. However, in this case, you 
must also take the default values for all subsequent qualifiers. To specify a 
pad character other than 0, place the ASCII value of the character you want 
to use in the PAD qualifier longword. 


If you specify /EXIT and the utility encounters an exception record, then 
CONVERT returns with a fatal exception status. 


If you specify an FDL file specification in the CONV$PASS_FILES routine, 
you must place a 1 in the FDL longword. If you also specify an exceptions 
file specification in the CONV$PASS_FILES routine, you must place a 1 in 
the EXCEPTION longword. You may specify either, both, or neither of these 
files, but the values in the CONV$PASS_FILES call must match the values in 
the parameter list. If they do not, the routine returns an error. 


If you specify the PROLOG longword, note that this overrides the KEY 
PROLOG attribute supplied by the FDL file. You must supply one of three 
values for the PROLOG longword if you use it. The three values are 0, 2, 
and 3. The value 0 means that you want to use the system or process prolog 
type. The value 2 means that you want to create a Prolog 1 or 2 file in 

all instances, even when circumstances would allow you to create a Prolog 
3 file. The value 3 means that you want to create a Prolog 3 file and, if 
circumstances do not allow you to, you want the conversion to fail. 
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flags 
VMS usage: 
type: 
access: 
mechanism: 


mask_longword 
longword (unsigned) 
read only 

by reference 


Flags (or masks) that control how the fdl_filespec argument is interpreted 
and how errors are signalled. The flags argument is the address of a 
longword containing the control flags (or a mask). If you omit this argument 
or specify it as zero, no flags are set. If you specify a flag, it remains in effect 
until you explicitly reset it in a subsequent call to a Convert routine. 


The flags and their meanings are described in the following table. 


Flag Function 

CONV$V_FDL_STRING Interprets the fdi_filespec argument supplied in the 
call to CONV$PASS_FILES as an FDL specification in 
string form. By default, this argument is interpreted 
as a file name of an FDL file. 

FDL$V_SIGNAL Signals any error. By default, the status code is 


returned to the calling image. 


This argument is optional. By default, an error status is returned rather than 


signalled. 





DESCRIPTION 
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The following example shows how to use the option array to reflect the 
CONVERT command: 


$ CONVERT/FAST_LOAD/SORT/WORK_F ILES=6/EXIT 


A: 12 


—_ 


- Ooo oom Hs OO = OO 


Specifies that 12 longwords follow 
Specifies the /CREATE option 
Specifies the /NOSHARE option 
Specifies the /FASTLOAD option 
Specifies the /NOMERGE option 
Specifies the /NOAPPEND option 
Specifies the /SORT option 
Specifies the /WORKFILES=6 option 
Specifies the /KEY=0 option 
Specifies the /NOPAD option 
Specifies the null pad character 
Specifies the /NOTRUNCATE option 
Specifies the /EXIT option 
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CONDITION 
VALUES | 
RETURNED 


SS$_NORMAL 
CONV$_BADBLK 
CONV$_CONFQUAL 
CONV$_INSVIRMEM 
CONV$_NARG 
CONV$_OPENEXC 
CONV$_ORDER 


Normal successful completion. 
Invalid option block. 

Conflicting qualifiers. 

Insufficient virtual memory. 

Wrong number of arguments. 

Error opening exception file filespec. 
Routine called out of order. 
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Convert (CONV) Routines 


CONVS$RECLAIM 


CONV$RECLAIM Invoke Convert/Reclaim Utility 


The CONV$RECLAIM routine invokes the functions of the Convert/Reclaim 
Utility. 











FORMAT CONVS$RECLAIM _input_filespec [, statistics_blk] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS __input_filespec 
VMS usage: char_string 
type: character-coded text string 
access: read only 
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mechanism: by descriptor—fixed-length string descriptor 


Name of the Prolog 3 indexed file to be reclaimed. The input_filespec 
argument is the address of a string descriptor pointing to the name of the 
Prolog 3 indexed file. 


statistics_blk 


VMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: modify 

mechanism: by reference 


Bucket reclamation statistics. The statistics_blk argument is the address 

of a variable-length array of longwords to receive statistics on the bucket 
reclamation. You can choose which statistics you want returned by specifying 
a number in the first element of the array. This number determines how 
many of the four possible statistics the routine returns. Depending on the 
number chosen, the routine returns the statistics in the statistics array in the 
order specified by the following format: 


A: Number of statistics 
Data buckets scanned 
Data buckets reclaimed 
Index buckets reclaimed 
Total buckets reclaimed 


Convert (CONV) Routines 
CONV$RECLAIM 





CONDITION 
VALUES 
RETURNED 


SS$_NORMAL 
CONV$_BADLOGIC 
CONV$_INSVIRMEM 
CONV$_INVBKT 
CONV$_NOTIDX 
CONV$_OPENIN 
CONV$_PLV 
CONV$_PROERR 
CONV$_PROL__WRT 
CONV$_READERR 
CONV$_NOWILD 
CONV$_WRITEERR 


Normal successful completion. 
Internal logic error detected. 
Insufficient virtual memory. 
Invalid bucket at VBN pn. 

File is not an index file. 

Error opening filespec as input. 
Unsupported prolog version. 
Error reading prolog. 

Prolog write error. 

Error reading filespec. 

No wildcard permitted. 


Error writing output file. 
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5 Data Compression/Expansion (DCX) Routines 





5.1 Introduction to DCX Routines 


The set of routines described in this chapter comprises the VMS Data 
Compression/Expansion (DCX) facility. There is no DCL-level interface 
to this facility nor is there a DCX Utility. 


Using the DCX routines described in this chapter, you can decrease the size 
of text, binary data, images, and any other type of data. Compressed data 
uses less space, but there is a trade-off in terms of access time to the data. 
Compressed data must first be expanded to its original state before it is 
usable. Thus, infrequently accessed data makes a good candidate for data 
compression. 


The DCX facility provides routines that analyze and compress data records 
and expand the compressed records to their original state. In this process, 
no information is lost. A data record that has been compressed and then 
expanded is in the same state as it was before it was compressed. 


Most collections of data can be reduced in size by DCX. However, there is 
no guarantee that the size of an individual data record will always be smaller 
after compression; in fact, some may grow larger. 


The DCX facility allows for the independent analysis, compression, and 
expansion of more than one stream of data records at the same time. This 
capability is provided by means of a “context variable,” which is an argument 
in each DCX routine. Most applications have no need for this capability; for 
these applications, there is a single context variable. 


The procedure for using the DCX routines to perform data compression and 
expansion consists of three major steps. The list under each of the following 
steps shows the DCX routines used to perform that step: 


1 Analyze some or all of the data records in the data file to produce a 
mapping function (or map). 


DCX$ANALYZE_INIT 
DCX$ANALYZE_DATA 
DCX$MAKE_MAP 
DCX$ANALYZE_DONE 


2 Compress the data records in the file on the basis of the mapping 
function. 


DCX$COMPRESS-_ INIT 
DCX$COMPRESS_DATA 
DCX$COMPRESS_DONE 


3 Expand the compressed data records on the basis of the mapping 
function. 


DCX$EXPAND_ INIT 
DCX$EXPAND_DATA 
DCX$EXPAND_DONE 
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5.2 


Data Compression/Expansion (DCX) Routines 
5.1 Introduction to DCX Routines 


Some of the DCX routines make calls to various Run-Time Library (RTL) 
routines, LIB$GET_VM, for example. If any of these RTL routines should fail, 
a return status code indicating the cause of the failure is returned. In such 

a case, you must refer to the documentation of the appropriate RTL routine 
to determine the cause of the failure. The status codes documented in this 
chapter are primarily DCX status codes. 





Examples of Using the DCX Routines 
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Examples 5-1 and 5-2 show how to use the DCX routines in VAX FORTRAN 
programs. . 


Example 5—1 Example of Compressing a File ina VAX FORTRAN 
Program 


PROGRAM COMPRESS_FILES 
! COMPRESSION OF FILES 


! status variable 
INTEGER STATUS, 


2 IOSTAT, 
2 IO_OK, 
2 STATUS_OK 


PARAMETER (IO_OK = 0) 
PARAMETER (STATUS_OK = 1) 
INCLUDE ' ($FORDEF)' 
EXTERNAL DCX$_AGAIN 


! context variable 

INTEGER CONTEXT 

! compression/expansion function 
INTEGER MAP, 

2 MAP_LEN 


! normal file name, length, and logical unit number 
CHARACTER*256 NORM_NAME 

INTEGER*2 NORM_LEN 

INTEGER NORM_LUN 

! compressed file name, length, and logical unit number 
CHARACTER*256 COMP_NAME 

INTEGER*2 COMP_LEN 

INTEGER COMP_LUN 


! Logical end-of-file 

LOGICAL EOF 

! record buffers; 32767 is maximum record size 
CHARACTER*32767 RECORD, 


2 RECORD2 
INTEGER RECORD_LEN, 
2 RECORD2_LEN 


! user routine 
INTEGER GET_MAP, 
2 WRITE_MAP 





Example 5—1 Cont'd. on next page 


Data Compression/Expansion (DCX) Routines 
5.2 Examples of Using the DCX Routines 


Example 5—1 (Cont.) Example of Compressing a File in a VAX 
FORTRAN Program 


! Library procedures 
INTEGER DCX$ANALYZE_INIT, 
DCX$ANALYZE_DONE, 
DCX$COMPRESS_INIT, 
DCX$COMPRESS_DATA, 
DCX$COMPRESS_DONE, 
LIB$GET_INPUT, 
LIB$GET_LUN, 
LIB$FREE_VM 


NNNONN ND 


i) 


! get name of file to be compressed and open it 
STATUS = LIB$GET_INPUT (NORM_NAME, 

2 'File to compress: ', 

2 NORM_LEN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (/ZVAL(STATUS) ) 
STATUS = LIB$GET_LUN (NORM_LUN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS) ) 
OPEN (UNIT = NORM_LUN, 

2 FILE = NORM_NAME(1:NORM_LENW) , 

2 CARRIAGECONTROL = 'NONE', 

2 STATUS = 'OLD') 


Pook RK Ro KK 

! ANALYZE DATA 

ettrtit tert ss. 

! initialize work area . 

STATUS = DCX$ANALYZE_INIT (CONTEXT) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (/ZVAL(STATUS) ) 
! get compression/expansion function (map) 
STATUS = GET_MAP (NORM_LUN, 


2 CONTEXT, 
2 MAP, 
2 MAP_LEN) 


DO WHILE (STATUS .EQ. %LOC(DCX$_AGAIN) ) 
! go back to beginning of file 
REWIND (UNIT = NORM_LUN) 

! try map again 
STATUS = GET_MAP (NORM_LUN, 


2 CONTEXT, 

2 MAP, 

2 MAP_LEN) 
END DO 


IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS) ) 
! clean up work area 

STATUS = DCX$ANALYZE_DONE (CONTEXT) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS) ) 


Example 5—1 Cont’d. on next page 
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Data Compression/Expansion (DCX) Routines 
5.2 Examples of Using the DCX Routines 


Example 5—1 (Cont.) Example of Compressing a File in a VAX 
FORTRAN Program 


ooo oR a RR ORK KK KK 

! COMPRESS DATA 

Dako oi ae 2 2 ok 2 2 2K 2K KK 

! go back to beeinning of file to be compressed 
REWIND (UNIT = NORM_LUN) ~ 

! open file to hold compressed records 

STATUS = LIB$GET_LUN (COMP_LUN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (AVAL (STATUS) ) 
STATUS = LIB$GET_INPUT (COMP_NAME, 

2 ‘File for compressed records: ', 
2 COMP_LEN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (/%VAL(STATUS) ) 
OPEN (UNIT = COMP_LUN, 


2 FILE = COMP_NAME(1:COMP_LEN) , 
2 STATUS = 'NEW', 
2 FORM = 'UNFORMATTED') 


! initialize work area 

STATUS = DCX$COMPRESS_INIT (CONTEXT, 

2 MAP) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS) ) 

! write compression/expansion function to new file 
CALL WRITE_MAP (COMP_LUN, 

2 “VAL (MAP) , 

2 MAP_LEN) 


! read record from file to be compressed 
EOF = .FALSE. 
READ (UNIT = NORM_LUN, 
2 FMT = '(Q,A)', 
2 IOSTAT = IOSTAT) RECORD_LEN, 
2 RECORD (1 : RECORD_LEN) 
IF (IOSTAT .NE. I0_OK) THEN 
CALL ERRSNS (,,,,STATUS) 
IF (STATUS .NE. FOR$_ENDDURREA) THEN 
CALL LIB$SIGNAL (/VAL(STATUS) ) 


ELSE 
EOF = .TRUE. 
STATUS = STATUS_OK 
END IF 

END IF 


Example 5—1 Cont'd. on next page 
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Data Compression/Expansion (DCX) Routines 
5.2 Examples of Using the DCX Routines 


Example 5—1 (Cont.) Example of Compressing a File in a VAX 
FORTRAN Program 


DO WHILE (.NOT. EOF) 

! compress the record 

STATUS = DCX$COMPRESS_DATA (CONTEXT, 
RECORD (1: RECORD_LEN) , 
RECORD2, 
RECORD2_LEN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS) ) 

! write compressed record to new file 

WRITE (UNIT = COMP_LUN) RECORD2_LEN 

WRITE (UNIT = COMP_LUN) RECORD2 (1:RECORD2_LEN) 

! read from file to be compressed 

READ (UNIT = NORM_LUN, 


bbw bd 


2 FMT = '(Q,A)', 
2 IOSTAT = IOSTAT) RECORD_LEN, 
2 RECORD (1:RECORD_LEN) 


IF (IOSTAT .NE. IO_OK) THEN 
CALL ERRSNS (,,,,STATUS) 
IF (STATUS .NE. FOR$_ENDDURREA) THEN 
CALL LIB$SIGNAL (VAL (STATUS) ) 


ELSE 
EOF = .TRUE. 
STATUS = STATUS_OK 
END IF 
END IF 
END DO 


! close files and clean up work area 

CLOSE (NORM_LUN) 

CLOSE (COMP_LUN) 

STATUS = LIB$FREE_VM (MAP_LEN, 

2 MAP) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS) ) 
STATUS = DCX$COMPRESS_DONE (CONTEXT) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS) ) 


END 

INTEGER FUNCTION GET_MAP (LUN, ! passed 

2 CONTEXT, ! passed 

2 MAP, ! returned 
2 MAP_LEN) ! returned 


! Analyzes records in file opened on logical 
! unit LUN and then attempts to create a 

! compression/expansion function using 

! DCX$MAKE_MAP. 


Example 5—1 Cont'd. on next page 
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5.2 Examples of Using the DCX Routines 
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Example 5—1 (Cont.) Example of Compressing a File in a VAX 
FORTRAN Program 


! dummy arguments 

! context variable 

INTEGER CONTEXT 

! logical unit number 

INTEGER LUN 

! compression/expansion function 
INTEGER MAP, 

2 MAP_LEN 


! status variable 
INTEGER STATUS, 


2 IOSTAT, 
2 IO_OK, 
2 STATUS_OK 


PARAMETER (IO_OK = 0) 
PARAMETER (STATUS_OK = 1) 
INCLUDE ' ($FORDEF) ' 


! Logical end-of-file 

LOGICAL EOF 

! record buffer; 32767 is the maximum record size 
CHARACTER*32767 RECORD 

INTEGER RECORD_LEN 


! library procedures 
INTEGER DCX$ANALYZE_DATA, 
2 DCX$MAKE_MAP 


! analyze records 
EOF =..FALSE. 
READ (UNIT = LUN, 
2 FMT = '(Q,A)', 
2 IOSTAT = IOSTAT) RECORD_LEN , RECORD 
IF (IOSTAT .NE. I0_OK) THEN 
CALL ERRSNS (,,,,STATUS) 
IF (STATUS .NE. FOR$_ENDDURREA) THEN 
CALL LIB$SIGNAL (%VAL(STATUS) ) 


ELSE 
EOF = .TRUE. 
STATUS = STATUS_OK 
END IF 

END IF 


Example 5—1 Cont'd. on next page 
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5.2 Examples of Using the DCX Routines 


Example 5—1 (Cont.) Example of Compressing a File in a VAX 
FORTRAN Program 


DO WHILE (.NOT. EOF) 

STATUS = DCX$ANALYZE_DATA (CONTEXT, 

2 RECORD (1: RECORD_LEN) ) 
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 
READ (UNIT = LUN, 

2 FMT = '(Q,A)', 

2 IOSTAT = IOSTAT) RECORD_LEN , RECORD 
IF (IOSTAT .NE. IO_OK) THEN 

CALL ERRSNS (,,,,STATUS) 
IF (STATUS .NE. FOR$_ENDDURREA) THEN 
CALL LIB$SIGNAL (%VAL(STATUS) ) 


ELSE 

EOF = . TRUE. 

STATUS = STATUS_OK 

END IF 

END IF 
END DO 

STATUS = DCX$MAKE_MAP (CONTEXT, 
2 MAP, 
2 MAP_LEN) 
GET_MAP = STATUS 
END 
SUBROUTINE WRITE_MAP (LUN, ! passed 
2 MAP, ! passed 
2 MAP_LEN) ! passed 


IMPLICIT INTEGER (A-Z) 
! write compression/expansion function 
! to file of compressed data 


! dummy arguments 

INTEGER LUN, ! logical unit of file 

2 MAP_LEN ! length of function 

BYTE MAP (MAP_LEN) ! compression/expansion function 


! write map length 

WRITE (UNIT = LUN) MAP_LEN 
! write map 

WRITE (UNIT = LUN) MAP 


END 
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Data Compression/Expansion (DCX) Routines 
5.2 Examples of Using the DCX Routines 


Example 5-2 Example of Expanding a Compressed File in a VAX 
FORTRAN Program 


PROGRAM EXPAND_FILES 
IMPLICIT INTEGER (A-Z) 
! EXPANSION OF COMPRESSED FILES 


! file names, lengths, and logical unit numbers 
CHARACTER*256 OLD_FILE, 

2 NEW_FILE 

INTEGER*2 OLD_LEN, 

2 NEW_LEN 

INTEGER OLD_LUN, 

2 NEW_LUN 


! length of compression/expansion function 
INTEGER MAP, 
2 MAP_LEN 


! user routine 
EXTERNAL EXPAND_DATA 


! library procedures 
INTEGER LIB$GET_LUN, 


2 LIB$GET_INPUT, 
2 LIB$GET_VM, 
2 LIB$FREE_VM 


! open file to expand 

STATUS = LIB$GET_LUN (OLD_LUN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS) ) 
STATUS = LIB$GET_INPUT (OLD_FILE, 

2 ‘File to expand: ', 

2 OLD_LEN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (/%VAL(STATUS) ) 
OPEN (UNIT = OLD_LUN, 

2 STATUS = 'OLD', 

2 FILE = OLD_FILE(1:OLD_LEN) , 

2 FORM = 'UNFORMATTED') 

! open file to hold expanded data 

STATUS = LIB$GET_LUN (NEW_LUN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS) ) 
STATUS = LIB$GET_INPUT (NEW_FILE, 

2 'File to hold expanded data: ', 
2 NEW_LEN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS) ) 
OPEN (UNIT = NEW_LUN, 

2 STATUS = 'NEW', 

2 CARRIAGECONTROL = 'LIST', 

2 FILE = NEW_FILE(4:NEW_LEN) ) 


Example 5—2 Cont’d. on next page 
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Data Compression/Expansion (DCX) Routines 
5.2 Examples of Using the DCX. Routines 


Example 5—2 (Cont.) Example of Expanding a Compressed File in a 
VAX FORTRAN Program 





! expand file 

! get length of compression/expansion function 
READ (UNIT = OLD_LUN) MAP_LEN 

STATUS = LIB$GET_VM (MAP_LEN, 

2 MAP) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (Z%VAL(STATUS) ) 
! expand records 

CALL EXPAND_DATA (%VAL(MAP), 


2 _ MAP_LEN, ! length of function 
2 OLD_LUN, ! compressed data file 
2 NEW_LUN) ! expanded data file 


! delete virtual memory used for function 
STATUS = LIB$FREE_VM (MAP_LEN, 


2 MAP) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS) ) 
END 

SUBROUTINE EXPAND_DATA (MAP, ! passed 

2 MAP_LEN, ! passed 

2 OLD_LUN, ! passed 

2 NEW_LUN) ! passed 


! expand data program 


! dummy arguments 
INTEGER MAP_LEN, 
2 OLD_LUN, 
2 NEW_LUN 
BYTE MAP (MAP_LEN) 


length of expansion function 
logical unit of compressed file 
logical unit of expanded file 
array containing the function 


! status variables 
INTEGER STATUS, 


2 IOSTAT, 
2 I0_OK, 
2 STATUS_OK 


PARAMETER (IO_OK = 0) 
PARAMETER (STATUS_OK = 1) 
INCLUDE ' ($FORDEF) ' 


! context variable 
INTEGER CONTEXT 


! logical end_of_file 
LOGICAL EOF 

! record buffers 
CHARACTER*32767 RECORD, 


2 RECORD2 
INTEGER RECORD_LEN, 
2 RECORD2_LEN 





Example 5—2 Cont'd. on next page 
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Example 5-2 (Cont.) Example of Expanding a Compressed File in a 
VAX FORTRAN Program 


! library procedures 

INTEGER DCX$EXPAND_INIT, 
2 DCX$EXPAND_DATA, 
2 DCX$EXPAND_DONE 


! read data compression/expansion function 
READ (UNIT = OLD_LUN) MAP 
! initialize work area 
STATUS = DCX$EXPAND_INIT (CONTEXT, 
2 LOC (MAP (1) )) 
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS) ) 
! expand records 
EOF = .FALSE. 
! read length of compressed record 
READ (UNIT = OLD_LUN, 
2 IOSTAT = IOSTAT) RECORD_LEN 
IF (IOSTAT .NE. IO_OK) THEN 
CALL ERRSNS (,,,, STATUS) 
IF (STATUS .NE. FOR$_ENDDURREA) THEN 
CALL LIB$SIGNAL ({%VAL(STATUS) ) 


ELSE 
EOF = .TRUE. 
STATUS = STATUS_OK 
END IF 

END IF 


DO WHILE (.NOT. EOF) 
! read compressed record 
READ (UNIT = OLD_LUN) RECORD (1:RECORD_LEN) 
! expand record 
STATUS = DCX$EXPAND_DATA (CONTEXT, 
2 RECORD (1: RECORD_LEN) , 
2 RECORD2, 
2 RECORD2_LEN) 
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS) ) 
! write expanded record to new file 
WRITE (UNIT = NEW_LUN, 
2 FMT = '(A)') RECORD2(1:RECORD2_LEN) 
! read length of compressed record 
READ (UNIT = OLD_LUN, 
2 IOSTAT = IOSTAT) RECORD_LEN 
IF (IOSTAT .NE. IO_OK) THEN 
CALL ERRSNS (,,,,STATUS) 
IF (STATUS .NE. FOR$_ENDDURREA) THEN 
CALL LIB$SIGNAL (%VAL(STATUS) ) 
ELSE 
EOF = .TRUE. 
STATUS = STATUS_OK 
END IF 
END IF 
END DO 
! clean up work area 
STATUS = DCX$EXPAND_DONE (CONTEXT) 
IF (.NOT. STATUS) CALL LIB$SIGNAL (/%VAL(STATUS) ) 
END 


Data Compression/Expansion (DCX) Routines 
5.3 DCX Routines 





5.3 DCX Routines 


The following pages describe the individual DCX routines. 
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DCX$ANALYZE_DATA 


DCX$ANALYZE_DATA Perform Statistical 


Analysis on a Data 
Record 
The DCX$ANALYZE_DATA routine performs statistical analysis on a data 


record. 


The results of the analysis are accumulated internally in the context area 
and are used by the DCX$MAKE_MAP routine to compute the mapping 
function. 





FORMAT 


DCX$ANALYZE_DATA context ,record 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 
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context 

VMS usage: context 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Value identifying the data stream that DCX$ANALYZE_DATA analyzes. 
The context argument is the address of a longword containing this value. 
DCX$ANALYZE_INIT initializes this value; you should not modify it. You 
can define multiple context arguments to identify multiple data streams that 
are processed simultaneously. 


record 

_VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor 


Record to be analyzed. DCX$ANALYZE_DATA reads the record argument, 
which is the address of a descriptor for the record string. The maximum 
length of the record string is 65,535 characters. 


Data Compression/Expansion (DCX) Routines 


DCX$ANALYZE_DATA 





DESCRIPTION 


The DCX$ANALYZE_DATA routine performs statistical analysis on a single 
data record. This routine is called once for each data record to be analyzed. 


During analysis, the data compression facility gathers information that 
DCX$MAKE_MAP uses to create the compression/expansion function 

for the file. After the data records have been analyzed, you call the 
DCX$MAKE_MAP routine. Upon receiving the DCX$_AGAIN status code 
from DCX$MAKE_MAP, you must again analyze the same data records (in 
the same order) using DCX$ANALYZE_DATA and then call 
DCX$MAKE_MAP again. On the second iteration, DCX$MAKE_MAP 
returns the DCX$_NORMAL status code, and the data analysis is complete. 





CONDITION 
VALUES 
RETURNED 


DCX$_INVCTX Error. The context variable is invalid, or the 
context area is invalid or corrupted. This may be 
caused by a failure to call the appropriate routine 
to initialize the context variable or by an application 
program error. 


DCX$_NORMAL Successful completion. 


This routine also returns any condition values returned by 
LIB$ ANALYZE_SDESC_R2. 
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DCX$ANALYZE_DONE 


DCX$ANALYZE_DONE Specify Analysis 
Completed 


The DCX$ANALYZE_DONE routine deletes the context area and sets the 
context variable to zero, thus undoing the work of the 
DCX$ANALYZE_INIT routine. 


You call DCX$ANALYZE_DONE after data records have been analyzed 
and the DCX$MAKE_MAP routine has created the map. 








FORMAT DCX$ANALYZE_DONE context 
RETURNS VMS usage: cond_value 

type: longword 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENT context 
VMS usage: context 
type: longword 
access: write only 
mechanism: by reference 


Value identifying the data stream that DCX$ANALYZE_DONE deletes. 
The context argument is the address of a longword containing this value. 
DCX$ANALYZE_INIT initializes this value; you should not modify it. You 
can define multiple context arguments to identify multiple data streams that 
are processed simultaneously. 





CONDITION Seay 2 Le 

VALUES DCX$_INVCTX Error. The context variable is invalid, or the 
context area is invalid or corrupted. This may be 

RETURNED caused by a failure to call the appropriate routine 


to initialize the context variable or by an application 
program error. 


DCX$_NORMAL Successful completion. 


This routine also returns any condition values returned by LIB$FREE_VM. 
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DCX$ANALYZE_INIT 


DCX$ANALYZE_INIT Initialize Analysis Context 


The DCX$ANALYZE_ INIT routine initializes the context area for a 
statistical analysis of the data records to be compressed. 





FORMAT DCX$ANALYZE_| NIT context [,item_code 
,tem_value] 





RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS ~ context 


VMS usage: context 

type: longword (unsigned) 
access: write only 
mechanism: by reference 


Value identifying the data stream that DCX$ANALYZE_INIT initializes. 
The context argument is the address of a longword containing this value. 
DCX$ANALYZE_INIT writes this context into the context argument; you 
should not modify its value. You can define multiple context arguments to 
identify multiple data streams that are processed simultaneously. 


item_code 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Item code specifying information that you want DCX$ANALYZE_INIT to use 
in its analysis of data records and in its computation of the mapping function. 
DCX$ANALYZE_INIT reads this item_—code argument, which is the address 
of the longword contained in the item code. 


For each item_—code argument specified in the call, you must also specify a 
corresponding item—value argument. The item_value argument contains 
the interpretation of the item—code argument. . 


The following symbolic names are the five legal values of the item—code 
argument: 


DCX$C_BOUNDED 
DCX$C_EST_BYTES 
DCX$C_EST_RECORDS 
DCX$C_LIST 
DCX$C_ONE_PASS 
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DCX$ANALYZE_INIT 


item_value 


VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Value of the corresponding item—code argument. DCX$ANALYZE_INIT 
reads the item_value argument, which is the address of a longword 
containing the item value. 


The item—code and item_—value arguments always occur as a pair, and 
together they specify one piece of “advice” for the DCX routines to use in 
computing the map function. Note that, unless stated otherwise in the list of 
item codes and item values, no piece of “advice” is binding on DCX; that is, 
DCX is free to follow or not to follow the “advice.” 


The following table shows, for each item—code argument, the possible values 
for the corresponding item—value argument. 


Item Code — Corresponding Item Value 


DCX$C_BOUNDED A Boolean variable. If bit <O> is true (equals 7), 
you are stating your intention to submit for analysis 
all data records that will be compressed; doing so 
often enables DCX to compute a better compression 
algorithm. If bit <O> is false (equals O) or if the 
DCX$C_BOUNDED item code is not specified, DCX 
computes a compression algorithm without regard for 
whether all records to be compressed will also be 
submitted for analysis. 


DCX$C_EST_BYTES A longword value containing your estimate of the 
total number of data bytes that will be submitted 
for compression. This estimate is useful in those 
cases where fewer than the total number of bytes 
are presented for analysis. If you do not specify the 
DCX$C_EST_BYTES item code, DCX submits for 
compression the same number of bytes that was 
presented for analysis. Note that you may specify 
DCX$C_EST_RECORDS or DCX$C_EST_BYTES, or 
both. 


DCX$C_EST_RECORDS A longword value containing your estimate of the 
total number of data records that will be submitted 
for compression. This estimate is useful in those 
cases where fewer than the total number of records 
are presented for analysis. If you do not specify the 
DCX$C_EST_RECORDS item code, DCX submits for 
compression the same number of bytes that was 
presented for analysis. 


DCX-—16 


Data Compression/Expansion (DCX) Routines 


Item Code 


DCX$C_LIST 


DCX$C_ONE_PASS 


DCX$ANALYZE_INIT 


Corresponding Item Value 


Address of an array of 2*n+1 longwords. The first 
longword in the array contains the value 2*n+1. The 
remaining longwords are paired; there are rn pairs. 
The first member of the pair is an item code, and 
the second member of the pair is the address of its 
corresponding item value. The DCX$C_LIST item 
code allows you to construct an array of item-code 
and item-value pairs and then to pass the entire array 
to DCX$ANALYZE_INIT. This is useful when your 
language has difficulty interpreting variable-length 
argument lists. Note that the DCX$C_LIST item code 
may be specified, in a single call, alone or together 
with any of the other item-code and item-value pairs. 


A Boolean variable. If bit <O> is true (equals 1), 
you make a binding request that DCX make only one 
pass over the data to be analyzed. If bit <O> is 
false (equals O) or if the DCX$C_ONE_PASS item 
code is not specified, DCX may make multiple passes 
over the data, as required. Typically, DCX makes one 
pass. 





DESCRIPTION 


The DCX$ANALYZE_INIT routine initializes the context area for a statistical 
analysis of the data records to be compressed. The first (and typically the 
only) argument passed to DCX$ANALYZE_INIT is an integer variable to 
contain the context value. The data compression facility assigns a value to the 
context variable and associates the value with the created work area. Each 
time you want a record analyzed in that area, specify the associated context 
variable. You can analyze two or more files at once by creating a different 
work area for each file, giving each area a different context variable, and 
analyzing the records of each file in the appropriate work area. 





CONDITION 
VALUES 
RETURNED 


DCX$_INVITEM 


DCX$_NORMAL 


Error; invalid item code. The number of arguments 
specified in the call was incorrect (this number 
should be odd), or an unknown item code was 
specified. 


Successful completion. 


This routine also returns any condition values returned by LIB$GET_VM. 
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DCX$COMPRESS_DATA Compress a Data 
Record 


The DCX$COMPRESS_DATA routine compresses a data record. You call 
this routine for each data record to be compressed. 





FORMAT DCX$COMPRESS_DATA context ,in_rec ,out_rec 
[,out_length] 





RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value. 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS context | 
VMS usage: context 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Value identifying the data stream that DCX$COMPRESS_DATA compresses. 
The context argument is the address of a longword containing this value. 
DCX$COMPRESS_INIT initializes the value; you should not modify it. You 
can define multiple context arguments to identify multiple data streams that 
are processed simultaneously. 


in_rec 

VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor — 


Data record to be compressed. The in_rec argument is the address of the 
descriptor of the data record string. 


out_rec 

VMS usage: char_string 
type: character string 
access: write only 


mechanism: by descriptor 


Data record that has been compressed. The out—_rec argument is the address 
of the descriptor of the compressed record that LIBS}COMPRESS_DATA 
returns. 
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out_length 

VMS usage: word_signed 

type: word integer (signed) 
access: write only 


mechanism: by reference 


Length (in bytes) of the compressed data record. The out_length argument is 
the address of a word into which LIB$}COMPRESS_DATA returns the length 
of the compressed data record. 





DESCRIPTION The DCX$COMPRESS_DATA routine compresses a data record. You call this 
routine for each data record to be compressed. As you compress each record, 
write the compressed record to the file containing the compression /expansion 
map. For each record, write the length of the record and substring string 
containing the record to the same file. See the COMPRESS DATA section in 





Example 5-1. 
CONDITION DCX$_INVCTX E Th iable is invalid h 
= rror. e context variable is invalid, or the 
VALUES context area is invalid or corrupted. This may be 
RETURNED caused by a failure to call the appropriate routine 


to initialize the context variable or by an application 
program error. 


DCX$_INVDATA Error. You specified the item value 
DCX$C_BOUNDED in the DCX$ANALYZE_INIT 
routine and attempted to compress a data record 
(using DCX$COMPRESS_DATA) that was not 
presented for analysis (using 
DCX$ANALYZE_DATA). Specifying the 
DCX$C_BOUNDED item value means that you must 
analyze all data records that are to be compressed. 


DCX$_INVMAP Error; invalid map. The map argument was not 
specified correctly or the context area is invalid. 

DCX$_NORMAL Successful completion. 

DCX$_TRUNC Error. The compressed data record has been 


truncated because the out_rec descriptor did 
not specify enough memory to accommodate the 
record. 


This routine also returns any condition values returned by 
LIBSANALYZE_SDESC_R2 and LIBSSCOPY_R_DxX. 
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DCX$COMPRESS_DONE Specify Compression 


Complete 


The DCX$COMPRESS_DONE routine deletes the context area and sets the 
context variable to zero. 





FORMAT 


DCX$COMPRESS_DONE context 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENT 


context 

VMS usage: context 

type: longword (unsigned) 
access: write only 
mechanism: by reference 


Value identifying the data stream that DCX$COMPRESS_DONE deletes. 
The context argument is the address of a longword containing this value. 
DCX$COMPRESS_INIT writes the value into context; you should not modify 
its value. You can define multiple context arguments to identify multiple data 
streams that are processed simultaneously. 





DESCRIPTION 


The DCX$COMPRESS_DONE routine deletes the context area and sets the 
context variable to zero, thus undoing the work of the DCX$COMPRESS_ 
INIT routine. You call DCX$COMPRESS_DONE when all data records 
have been compressed (using DCX$COMPRESS_DATA). After calling 
DCX$COMPRESS_DONE, call LIB$FREE—_VM to free the virtual memory 
that DCX$MAKE_MAP used for the compression/expansion function. 





CONDITION 
VALUES 
RETURNED 
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DCX$_INVCTX Error. The context variable is invalid or the context 
area is invalid or corrupted. This may be caused by 
a failure to call the appropriate routine to initialize 
the context variable or by an application program 
error. 


DCX$_NORMAL Successful completion. 


This routine also returns any condition values returned by LIB$FREE_VM. 
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DCX$COMPRESS_ INIT Initialize Compression 
Context 


The DCX$COMPRESS_ INIT routine initializes the context area for the 
compression of data records. 








FORMAT DCXS$COMPRESS_INIT context ,map 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. , 





ARGUMENTS context 
VMS usage: context 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


Value identifying the data stream that DCX$COMPRESS_INIT initializes. 
The context argument is the address of a longword containing this value. 
You should not modify the context value after DCX$COMPRESS_INIT 
initializes it. You can define multiple context arguments to identify multiple 
data streams that are processed simultaneously. 


map 

VMS usage: address 

type: longword (unsigned) 
access: read only 


mechanism: by reference 


The function created by DCX$MAKE_MAP. The map argument is the 
address of the compression/expansion function’s virtual address. 


The map argument must remain at this address until data compression is 
completed and the context is deleted by means of a call to 
DCX$COMPRESS_DONE. 





DESCRIPTION — The DCX$COMPRESS_INIT routine initializes the context area for the 
_ compression of data records. 


You call the DCX$COMPRESS_INIT routine after the call to 
DCX$ANALYZE_DONE. 
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CONDITION — 
VALUES DCX$_INVMAP Error; invalid map. The map argument was not 


specified correctly, or the context area is invalid. 
RETURNED DCX$_NORMAL Successful completion. 


This routine also returns any condition values returned by LIBSGET_VM and 
LIB$FREE_VM. 
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DCX$EXPAND_DATA Expand a Compressed 
Data Record 


The DCX$EXPAND_DATA routine expands (or restores) a compressed 
data record to its original state. 





FORMAT DCX$EXPAND_DATA context ,in_rec ,out_rec 
[,out_length] 





RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS context 
VMS usage: context 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Value identifying the data stream that DCX$EXPAND_DATA expands. 

The context argument is the address of a longword containing this value. 
DCX$EXPANDLINIT initializes this value; you should not modify it. You can 
define multiple context arguments to identify multiple data streams that are 
processed simultaneously. 


in_rec 

VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor 


Data record to be expanded. The in_rec argument is the address of the 
descriptor of the data record string. 


out_rec 

VMS usage: char_string 
type: character string 
access: write only 


mechanism: by descriptor 


Data record that has been expanded. The out_rec argument is the address of 
the descriptor of the expanded record returned by DCX$EXPAND_DATA. 
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out_length 

VMS usage: word_signed 

type: word integer (signed) 
access: write only 
mechanism: by reference 


Length (in bytes) of the expanded data record. The out—_length argument is 
the address of a word into which DCX$EXPAND_DATA returns the length of 
the expanded data record. 





DESCRIPTION The DCX$EXPAND_DATA routine expands (or restores) a compressed data 
record to its original state. You call this routine for each data record to be 





expanded. 
CONDITION DCX$_INVCTX E Th iable is invalid h 
ae rror. e context variable is invalid, or the 
VALUES context area is invalid or corrupted. This may be 
RETURNED | caused by a failure to call the appropriate routine 
to initialize the context variable or by an application 
program error. 
DCX$_INVDATA Error. A compressed data record is invalid 
(probably truncated) and therefore cannot be 
expanded. 
DCX$_INVMAP Error; invalid map. The map argument was not 
specified correctly, or the context area is invalid. 
DCX$_NORMAL Successful completion. 
DCX$_TRUNC Warning. The expanded data record has been 


truncated because the out_rec descriptor did 
not specify enough memory to accommodate the 
record. 


This routine also returns any condition values returned by 
LIBS ANALYZE_SDESC_R2 and LIB$SCOPY_R_Dx. 
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DCX$EXPAND_DONE Specify Expansion 
Complete 


The DCX$EXPAND_DONE routine deletes the context area and sets the 
context variable to zero. 








FORMAT DCX$EXPAND_DONE context 

RETURNS VMS usage: cond_value_. 

type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENT context 
VMS usage: context 
type: longword (unsigned) 
access: _ write only 
mechanism: by reference 


Value identifying the data stream that DCX$EXPAND_DONE deletes. 

The context argument is the address of a longword containing this value. 
DCX$EXPAND_LINIT initializes this value; you should not modify it. You can 
define multiple context arguments to identify multiple data streams that are 
processed simultaneously. 





DESCRIPTION The DCX$EXPAND_DONE routine deletes the context area and sets the 
context variable to zero, thus undoing the work of the DCX$EXPAND_INIT 
routine. You call DCX$EXPAND_DONE when all data records have been 
expanded (using DCX$EXPAND_DATA). 





CONDITION DCX$_INVCTX E Th iable is invalid h 

= rror. e context variable is invalid, or the 
VALU ES context area is invalid or corrupted. This may be 
RETURNED caused by a failure to call the appropriate routine 


to initialize the context variable or by an application 
program error. 


DCX$NORMAL Successful completion. 


This routine also returns any condition values returned by LIBSFREE_VM. 
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DCX$EXPAND_INIT Initialize Expansion Context 


The DCX$EXPAND_INIT routine initializes the context area for the 
expansion of data records. 








FORMAT DCX$EXPAND_INIT context ,map 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only . 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS context 
VMS usage: context 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


Value identifying the data stream that DCX$EXPAND_INIT initializes. The 
context argument is the address of a longword containing this value. After 
DCX$EXPAND_INIT initializes this context value, you should not modify it. 
You can define multiple context arguments to identify multiple data streams 
that are processed simultaneously. 


map 

VMS usage: address 

type: longword (unsigned) 
access: read only 


mechanism: by reference 


Compression /expansion function (created by DCX$MAKE-—MAP). The map 
argument is the address of the compression/expansion function’s virtual 
address. 


The map argument must remain at this address until data expansion is 
completed and context is deleted by means of a call to 
DCX$EXPAND_DONE. 





DESCRIPTION — The DCX$EXPAND_LINIT routine initializes the context area for the 
expansion of data records. 


You call the DCX$EXPAND_INIT routine as the first step in the expansion 
(or restoration) of compressed data records to their original state. 
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Before you call DCX$EXPAND_INIT, read the length of the compressed file 
from the compression/expansion function (the map). Invoke LIB$GET_VM to 


get the necessary amount of storage for the function. LIBSGET_VM returns 
the address of the first byte of the storage area. 





CONDINION DCX$_INVMAP E invalid Th 

. a rror; invalid map. The map argument was not 
VALUES specified correctly, or the context area is invalid. 
RETURNED DCX$_NORMAL Successful completion. 


This routine also returns any condition values returned by LIB$GET_VM. 
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DCX$MAKE_MAP | 


DCX$MAKE_MAP Compute the 
Compression/Expansion 
Function 


The DCX$MAKE_MAP routine uses the statistical information gathered by 
DCX$ANALYZE_DATA to compute the compression/expansion function. 








FORMAT DCX$MAKE_MAP context ,map_adadr [,map_size] 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS context | 
VMS usage: context 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


Value identifying the data stream that DCX$MAKE_MAP maps. The 
context argument is the address of a longword containing this value. 
DCX$ANALYZE_INIT initializes this value; you should not modify it. You 
can define multiple context arguments to identify multiple data streams that 
are processed simultaneously. 


map_—addr 

VMS usage: address 

type: longword (unsigned) 
access: write only 
mechanism: by reference 


Starting address of the compression/expansion function. The map—addr 
argument is the address of a longword into which DCX$MAKE_MAP stores 
the virtual address of the compression/expansion function. 


map-_size 

VMS usage: longword_signed 
type: longword (unsigned) 
access: write only 


mechanism: by reference 


Length of the compression/expansion function. The map_size argument is 
the address of the longword into which DCX$MAKE_MAP writes the length 
of the compression/expansion function. This is an optional argument. 
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DCX$MAKE_MAP 





DESCRIPTION 


The DCX$MAKE_MAP routine uses the statistical information gathered by 
DCX$ANALYZE_DATA to compute the compression/expansion function. In 
essence, this map is the algorithm used to shorten (or compress) the original 
data records as well as to expand the compressed records to their original 
form. - 9 


The map must be available in memory when any data compression or 
expansion takes place; the address of the map is passed as an argument to the 
DCX$COMPRESS_INIT and DCX$EXPAND_LINIT routines, which initialize 
the data compression and expansion procedures, respectively. 


The map is stored with the compressed data records, because the compressed 
data records are indecipherable without the map. When compressed data 
records have been expanded to their original state and no further compression 
is desired, you should delete the map using the LIBSFREE_VM routine. _ 


DCX requires that you submit data records for analysis and then call the 
DCX$MAKE_MAP routine. Upon receiving the DCX$_AGAIN status code, 
you must again submit data records for analysis (in the same order) and call 
DCX$MAKE_MAP again; on the second iteration, DCX$MAKE_MAP returns 
the DCX$_NORMAL status code. 





CONDITION 
VALUES 
RETURNED 


DCX$_AGAIN Informational. The map has not been created 
and the map_addr and map_size arguments 
have not been written because further analysis 
is required. The data records must be analyzed 
(using DCX$ANALYZE_DATA) again, and 
DCX$MAKE_MAP must be called again before 
DCX$MAKE_MAP will create the map and return 
the DCX$_NORMAL status code. 


DCX$_INVCTX Error. The context variable is invalid, or the 
context area is invalid or corrupted. This may be 
caused by a failure to call the appropriate routine 
to initialize the context variable or by an application 
program error. 


DCX$_NORMAL Successful completion. 


This routine also returns any condition values returned by LIB}|GET_VM and 
LIB$FREE_VM. 
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Introduction to EDT Routines 


On VMS operating systems, the EDT editor can be called from a program. 
Calling programs can be written in any VAX language that generates calls 
using the VAX Procedure Calling and Condition Handling Standard. 


You can set up your call to EDT so that the program handles all the editing 
work, or you can make EDT run interactively so that you can edit a file while 
the program is running. 


This chapter on callable EDT assumes that you know how to call an external 
facility from the language you are using. Callable EDT is a shareable image, 
which means that you save physical memory and disk space by having all 
processes access a single copy. 


You must include a statement in your program accessing the EDT entry point. 
This reference statement is similar to a library procedure reference statement. 
The EDT entry point is referenced as EDT$EDIT. You can pass arguments 

to EDT$EDIT; for example, you can pass EDT$FILEIO or your own routine. 
When you refer to the routines you pass, call them FILEIO, WORKIO, and 
XLATE. Therefore, FILEIO can be either a routine provided by EDT (named 
EDT$FILEIO) or a routine that you write. 





Example of Using EDT Routines 


Example 6-1 shows a VAX BASIC program that calls EDT. All three routines 
(FILEIO, WORKIO, and XLATE) are called. Note the reference to the entry 
point EDT$EDIT in line number 500. 


Example 6—1 Using the EDT Routines in a VAX BASIC Program 


100 EXTERNAL INTEGER EDT$FILEIO @ 
200 EXTERNAL INTEGER EDT$WORKIO 

250 EXTERNAL INTEGER AXLATE 

300 EXTERNAL INTEGER FUNCTION EDT$EDIT 
400 DECLARE INTEGER RESULT 


450 DIM INTEGER PASSFILE(1%) @ 
460 DIM INTEGER PASSWORK(1%) 

465 DIM INTEGER PASSXLATE(1%) 

470 PASSFILE(0%) = LOC(EDT$FILEIO) 
480 PASSWORK(0%) = LOC(EDT$WORKIO) 
485 PASSXLATE(0%) = LOC(AXLATE) 


Example 6—1 Cont'd. on next page 


EDT-1 


EDT Routines 
6.2 Example of Using EDT Routines 


Example 6—1 (Cont.) Using the EDT Routines in a VAX BASIC 
Program 


500 RESULT = EDT$EDIT('FILE.BAS','','EDTINI','',o%, © 
PASSFILE(0%)BY REF, PASSWORK(0%) BY REF, @ 
PASSXLATE(0%) BY REF)  @ 

600 IF (RESULT AND 1%) = 0% 

THEN - 
PRINT "SOMETHING WRONG" 
CALL LIB$STOP(RESULT BY VALUE) 

900 PRINT "EVERYTHING 0.K." 

1000 END 


@ The external entry points EDT$FILEIO, EDT$WORKIO, and AXLATE are 
defined so that they can be passed to callable EDT. 


@ Arrays are used to construct the two-longword structure needed for data 
type BPV. 


© Here is the call to EDT. The input file is FILE.BAS, the output and journal 
files are defaulted, and the command file is EDTINI. A 0 is passed for the 
options word to get the default EDT options. 


@ The array PASSFILE points to the entry point for all file 1/O, which is set 
up in this example to be the EDT-supplied routine with the entry point 
EDT$FILEIO. Similarly, the array PASSWORK points to the entry point 
for all work I/O, which is the EDT-supplied routine with the entry point 
EDT$WORKIO. 


@ PASSXLATE points to the entry point that EDT will use for all XLATE 
processing. PASSXLATE points to a user-supplied routine with the entry 
point AXLATE. 





6.3 EDT Routines 


The following pages describe the individual EDT routines. 
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EDT$SEDIT 
EDTSEDIT Edit a File 
The EDT$EDIT atae invokes the EDT editor. 
FORMAT EDTS$EDIT  in_file [,out_file] [, com_file] [, jou_file] 


[_options] [,fileto] [, workio] [,xlate] 





RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS in_file 
VMS usage: char_string 
type: character-coded text string 
access: read only 
mechanism: by descriptor 


File specification of the input file that EDT$EDIT is to edit. The in_file 
argument is the address of a descriptor pointing to this file specification. The 
string that you enter in this calling sequence is passed to the FILEIO routine 
to open the primary input file. This is the only required argument. 


out_file 

VMS usage: char_string 

type: character-coded text string 
access: read only 


mechanism: by descriptor 


File specification of the output file that EDT$EDIT creates. The out_file 
argument is the address of a descriptor pointing to this file specification. The 
default is that the input file specification is passed to the FILEIO routine to 
open the output file for the EXIT command. 


com_tfile 

VMS usage: char_string 

type: character-coded text string 
access: read only 

mechanism: by descriptor 


File specification of the startup command file to be executed when EDT is 
invoked. The com_file argument is the address of a descriptor pointing to 
this file specification. The com-_file string is passed to the FILEIO routine to 
open the command file. The default is the same as that for EDT command 
file defaults. 
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jou_file 

VMS usage: char_string 

type: character-coded text string 
access: read only 


mechanism: by descriptor 


File specification of the journal file to be opened when EDT is invoked. 

The jou_file argument is the address of a descriptor pointing to this file 
specification. The jou_file string is passed to the FILEJO routine to open the 
journal file. The default is to use the same file name as in_file. 


options 

VMS usage: mask—longword 
type: aligned bit string 
access: read only 


mechanism: by reference 


Bit vector specifying options for the edit operation. The options argument 

is the address of an aligned bit string containing this bit vector. Only bits 
<5:0> are currently defined; all others must be 0. The default options have 
all bits set to 0. This is the same as the default setting when you invoke EDT 
to edit a file from DCL. 


Symbols and their descriptions follow: 


EDT$M_RECOVER If set, bit <O> causes EDT to read the journal file 
and execute the commands in it, except for the EXIT 
or QUIT commands, which are ignored. After the 
journal file commands are processed, editing continues 
normally. If bit <O> is set, the FILEIO routine is 
asked to open the journal file for both input and output; 
otherwise FILEIO is asked only to open the journal file 
for output. Bit <O> corresponds to the /RECOVER 
qualifier on the EDT command line. 


EDT$M_COMMAND If set, bit <1> causes EDT to signal if the startup 
command file cannot be opened. When bit <1> 
is O, EDT intercepts the signal from the FILEIO 
routine indicating that the startup command file 
could not be opened. Then, EDT proceeds with 
the editing session without reading any startup 
command file. If no command file name is supplied 
with the call to the EDT$EDIT routine, EDT tries 
to open SYS$LIBRARY:EDTSYS.EDT or, if that 
fails, EDTINI.EDT. Bit <1> corresponds to the 
/COMMAND qualifier on the EDT command line. If 
EDT$M_NOCOMMAND (bit <4> ) is set, bit <1> 
is overridden because bit <4> prevents EDT from 
trying to open a command file. 


EDT$M_NOJOURNAL If set, bit <2> prevents EDT from opening the journal 
file. Bit <2> corresponds to the /NOJOURNAL or 
/READ_ONLY qualifier on the EDT command line. 


EDT$M_NOOUTPUT If set, bit <3> prevents EDT from using the input 
file name as the default output file name. Bit <3> 
corresponds to the /NOOUTPUT or /READ_ONLY 
qualifier on the EDT command line. 


EDT Routines 
EDTSEDIT 


EDT$M_NOCOMMAND _If set, bit <4> prevents EDT from opening a 
startup command file. Bit <4> corresponds to 
the /NOCOMMAND qualifier on the EDT command line. 


EDT$M_NOCREATE If set, bit <5> causes EDT to return to the caller if 
the input file is not found. The status returned is the 
error code EDT$_INPFILNEX. 


fileio 

VMS usage: vector_longword_unsigned 
type: bound procedure value 
access: function call 


mechanism: by reference 


User-supplied routine called by EDT to perform file I/O functions. The fileio 
argument is the address of a bound procedure value containing the user- 
supplied routine. When you do not need to intercept any file I/O, either use 
the entry point EDT$FILEIO for this argument or omit it. When you only 
need to intercept some amount of file I/O, call the EDT$FILEIO routine for 
the other cases. 


To avoid confusion, note that EDT$FILEIO is a routine provided by EDT 
whereas FILEIO is a routine that you provide. 


In order to accommodate routines written in high-level languages that do 
up-level addressing, this argument must have a data type of BPV (bound 
procedure value). BPV is a two-longword entity in which the first longword 
contains the address of a procedure entry mask and the second longword is 
the environment value. When the bound procedure is called, EDT loads the 
second longword into R1. If you use EDT$FILEIO for this argument, set the 
second longword to <0>. You can passa <0O> for the argument, and 
EDT will set up EDT$FILEIO as the default and set the environment word 
to 0. 


workio 

VMS usage: vector_longword_unsigned 
type: bound procedure value 
access: function call 


mechanism: by reference 


User-supplied routine called by EDT to perform I/O between the work file 
and EDT. The workio argument is the address of a bound procedure value 
containing the user-supplied routine. Work file records are addressed only by 
number and are always 512 bytes long. If you do not need to intercept work 
file I/O, you can either use the entry point EDT$WORKIO for this argument 
or omit it. 


In order to accommodate routines written in high-level languages that do 
up-level addressing, this argument must have a data type of BPV (bound 
procedure value). This means that EDT loads R1 with the second longword 
addressed before calling it. If EDT$WORKIO is used for this argument, set 
the second longword to 0. You can pass a 0 for this argument, and EDT will 
set up EDT$WORKIO as the default and set the environment word to 0. 
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xlate 

VMS usage: vector_longword_unsigned 
type: bound procedure value 
access: function call 


mechanism: by reference 


User-supplied routine that EDT calls when it encounters the nokeypad 
command XLATE. The xlate argument is the address of a bound procedure 
value containing the user-supplied routine. The XLATE routine allows you to 
gain control of your EDT session. If you do not need control of EDT during 
the editing session, you can either use the entry point EDT$XLATE for this 
argument or omit it. 


In order to accommodate routines written in high-level languages that do 
up-level addressing, this argument must have a data type of BPV (bound 
procedure value). This means that EDT loads R1 with the second longword 
addressed before calling it. If EDT$XLATE is used for this argument, set the 
second longword to 0. You can pass a 0 for this argument, and EDT will set 
up EDT$XLATE as the default and set the environment word to 0. 





DESCRIPTION 


If the EDT session is terminated by EXIT or QUIT, the status will be a 
successful value (bit <0> = 1). If the session is terminated because the file 
was not found and if the /NOCREATE qualifier was in effect, the failure code 
EDT$_INPFILNEX is returned. In an unsuccessful termination caused by an 
EDT error, a failure code corresponding to that error is returned. Each error 
status from the FILEIO and WORKIO routines is explained separately. 


Three of the arguments to the EDT$EDIT routine, fileio, workio, and xlate 
are the entry point names of user-supplied routines. _ 





CONDITION 
VALUES 
RETURNED 
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SS$_NORMAL Successful completion. ; 
EDT$_INPFILNEX /NOCREATE specified and input file does not exist. 


This routine also returns any condition values returned by user-supplied 
routines. 


FILEIO 


EDT Routines 
FILEIO 


The user-supplied FILEIO routine performs file |/O functions. You call it by 
specifying it as an argument in the EDT$EDIT routine. It cannot be called 
independently. 











FORMAT FILEIO code ,stream ,record ,rhb 
RETURNS VMS usage: cond_value 
| type: longword (unsigned) 

access: write only 
mechanism: by value 
A VMS status code that your FILEIO routine returns to EDT$EDIT. The fileio 
argument is a longword containing the status code. The only failure code 
that is normally returned is RMS$_EOF from a GET call. All other VMS 
RMS errors are signaled, not returned. The VMS RMS signal should include 
the file name and both longwords of the RMS status. Any errors detected 
with the FILEJO routine can be indicated by setting status to an error code. 
That special error code will be returned to the program by the EDT$EDIT 
routine. There is a special status value EDT$_NONSTDFIL for nonstandard 
file opening. 
Condition values are returned in RO. 

ARGUMENTS ~~ code 
VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


A code from EDT that specifies what function the FILEIO routine is to 
perform. The code argument is the address of a longword integer containing 
this code. Following are the valid function codes: 


Function Code Description 


EDT$K_OPEN_INPUT The record argument names a file to be 
opened for input. The rhb argument is the 
default file name. 

EDT$K__OPEN_OUTPUT_SEQ The record argument names a file to be 
opened for output as a sequenced file. The 
rhb argument is the default file name. 

EDT$K__OPEN__OUTPUT_NOSEO The record argument names a file to be 
opened for output. The rhb argument is the 
default file name. . 
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Function Code 
EDT$K_OPEN_IN_OUT 


EDT$K_GET 


EDT$K_PUT 


EDT$K_CLOSE_DEL 


EDT$K_CLOSE 


Description 


The record argument names a file to be 
opened for both input and output. The rhb 
argument is the default file name. 


The record argument is to be filled with 
data from the next record of the file. If the 
file has record prefixes, rhb is filled with 
the record prefix. If the file has no record 
prefixes, rhb is not written. When you 
attempt to read past the end of file, status 
is set to RMS$_EOF. 


The data in the record argument is to be 
written to the file as its next record. If the 
file has record prefixes, the record prefix 
is taken from the rhb argument. For a file 
opened for both input and output, 
EDT$K_PUT is valid only at the end of 
the file, indicating that the record is to be 
appended to the file. 


The file is to be closed and then deleted. 
The record and rhb arguments are not used 
in the call. 


The file is to be closed. The record and 
rhb arguments are not used in the call. 


stream 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


A code from EDT that indicates which file is being used. The stream 
argument is the address of a longword integer containing the code. Following 


are the valid codes. 


Function Code 


EDT$K__COMMAND_FILE 
EDT$K_INPUT_FILE 
EDT$K_INCLUDE _FILE 


EDT$K_JOURNAL _FILE 
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Description 


The command file. 
The primary input file. 


The secondary input file. Such a file is opened in 
response to an INCLUDE command. It is closed 
when the INCLUDE command is complete and will 
be reused for subsequent INCLUDE commands. 


The journal file. If bit O of the options is set, it 

is opened for both input and output and is read 
completely. Otherwise, it is opened for output 
only. After it is read or opened for output only, it 
is used for writing. On a successful termination of 
the editing session, the journal file is closed and 
deleted. EXIT/SAVE and QUIT/SAVE close the 
journal file without deleting it. 


EDT Routines 


FILEIO 
Function Code Description 
EDT$K_OUTPUT_FILE The primary output file. It is not opened until you 
enter the EXIT command. 
EDT$K_WRITE_FILE The secondary output file. Such a file is opened 


in response to a WRITE or PRINT command. It 
is closed when the command is complete and 
will be reused for subsequent WRITE or PRINT 


commands. 
record 
VMS usage: char_string 
type: character-coded text string 
access: modify 


mechanism: by descriptor 


Text record passed by descriptor from EDT to the user-supplied FILEIO 
routine; the code argument determines how the record argument is used. 
The record argument is the address of a descriptor pointing to this argument. 
When the code argument starts with EDT$K_OPEN, the record is a file 
name. When the code argument is EDT$K_GET, the record is a place to 
store the record that was read from the file. For code argument EDT$K_PUT, 
the record is a place to find the record to be written to the file. This argument 
is not used if the code argument starts with EDT$K_CLOSE. 


Note that for EDT$K_GET, EDT uses a dynamic or varying string descriptor; 
otherwise, EDT has no way of knowing the length of the record being read. 
EDT uses only string descriptors that can be handled by the Run-Time Library 
(RTL) routine STR6COPY_DX. 


rhb 

VMS usage: char_string 

type: character-coded text string 
access: modify 


mechanism: by descriptor 


Text record passed by descriptor from EDT to the user-supplied FILEIO 
routine; the code argument determines how the rhb argument is used. 
When the code argument starts with EDT$K_OPEN, the rhb argument 

is the default file name. When the code is EDT$K_GET and the file has 
record prefixes, the prefixes are put in this argument. When the code is 
EDT$K_PUT and the file has record prefixes, the prefixes are taken from 
this argument. Like the record argument, EDT uses a dynamic or varying 
string descriptor for EDT$K—_GET and uses only string descriptors that can be 
handled by the RTL routine STR$6COPY_DX. 
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DESCRIPTION If you do not need to intercept any file I/O, you can use the entry point 
EDT$FILEIO for this argument or you can omit it. If you need to intercept 
only some file I/O, call the EDT$FILEIO routine for the other cases. 


When you use EDT$FILEIO as a value for the fileio argument, files are 
opened as follows: 


e The record argument is always the RMS file name. 
e The rhb argument is always the RMS default file name. 
e There is no related name for the input file. 


e The related name for the output file is the input file with OFP (output file 
parse). EDT passes the input file name, the output file name, or the name 
from the EXIT command in the record argument. 


e The related name for the journal file is the input file name with the 
output file parse (OFP) RMS bit set. 


e The related name for the INCLUDE file is the input file name with the 
OFP set. This is unusual because the file is being opened for input. 





CONDITION | 
VALUES SS$_NORMAL Successful completion. 
RETURNED EDT$_NONSTDFIL File is not in standard text format. 


RMS$_EOF End of file on a GET. 
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The user-supplied WORKIO routine is called by EDT when it needs 
temporary storage for the file being edited. You call it by specifying it as 
an argument in the EDT$EDIT routine. It cannot be called independently. 





FORMAT 


WORKIO code ,recordno ,record 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by immediate value 


Longword value returned as a VMS status code. It is generally a success 
code, because all VMS RMS errors should be signaled. The signal should 
include the file name and both longwords of the VMS RMS status. Any 
errors detected within work I/O can be indicated by setting status to an error 
code, which will be returned by the EDT$EDIT routine. 


The condition value is returned in RO. 





ARGUMENTS 


code 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


A code from EDT that specifies the operation to be performed. The code 
argument is the address of a longword integer containing this argument. The 
valid function codes are as follows: 


Function Code Description 


EDT$K_OPEN_IN_OUT Open the work file for both input and output. Neither 


the record nor recordno argument is used. 


EDT$K_GET Read a record. The recordno argument is the number 
of the record to be read. The record argument gives 
the location where the record is to be stored. 


EDT$K_PUT Write a record. The recordno argument is the 
number of the record to be written. The record 
argument tells the location of the record to be 
written. 


EDT$K_CLOSE_DEL Close the work file. After a successful close, the file 
is deleted. Neither the record nor recordno argument 
is used. 
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WORKIO 
recordno 
VMS usage: longword_signed 
type: longword integer (signed) 
access: read only | 
mechanism: by reference 
Number of the record to be read or written. The recordno argument is the 
address of a longword integer containing this argument. EDT always writes a 
record before reading that record. This argument is not used for open or close 
calls. 
record 
VMS usage: char_string 
type: character string 
access: modify 
mechanism: by descriptor 
Location of the record to be read or written. This argument always refers to 
a 512-byte string during GET and PUT calls. This argument is not used for 
open or close calls. 

DESCRIPTION | Work file records are addressed only by number and are always 512 bytes 
long. If you do not need to intercept work file I/O, you can use the entry 
point EDT$WORKIO for this argument or you can omit it. 

owen SS$_NORMAL S ful leti 

VALUE a uccesstui completion. 

RETURNED 
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XLATE 


The user-supplied XLATE routine is called by EDT when it encounters the 
nokeypad command XLATE. You cause it to be called by specifying it as 
an argument in the EDT$EDIT routine. It cannot be called independently. 








FORMAT XLATE string 

RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword value returned as a VMS status code. It is generally a success code. 
If the XLATE routine cannot process the passed string for some reason, it sets 
status to an error code. Returning an error code from the XLATE routine 
aborts the current key execution and displays the appropriate error message. 


The condition value is returned in RO. 





ARGUMENT string 
VMS usage: char_string 
type: character-coded text string 
access: modify 
mechanism: by descriptor 


Text string passed to the nokeypad command XLATE. You can use the 
nokeypad command XLATE by defining a key to include the following 
command in its definition: 


XLATEtext~Z 


The text is passed by the string argument. The string argument is one that 
can be handled by the Run-Time Library (RTL) routine STR$6COPY_DX. 


This argument is also a text string returned to EDT. The string is made up of 
nokeypad commands that EDT is to execute. 





DESCRIPTION The nokeypad command XLATE allows you to gain control of the EDT 
session. (See the VAX EDT Reference Manual for more information about the 
XLATE command.) If you do not need to gain control of EDT during the 
editing session, you can use the entry point EDT$XLATE for this argument or 
you can omit it. 





CONDITION | 
VALUE SS$_NORMAL Successful completion. 


RETURNED 
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7.1 Introduction to FDL Routines 


This chapter describes the File Definition Language (FDL) routines. These 
routines perform many of the functions of the RMS File Definition Language. 


The FDL$CREATE routine is the one most likely to be called from a high- 
level language. It creates a file from an FDL specification and then closes the 
file. 


The following three FDL routines provide a way to specify all the options 
RMS allows when it executes create, open, or connect operations. They also 
allow you to specify special processing options required for your applications. 


The FDL$GENERATE routine produces an FDL specification by interpreting 
a set of RMS control blocks. It then writes the FDL specification either to an 
FDL file or to a character string. 


The FDL$PARSE routine parses an FDL specification, allocates RMS control 
blocks, and fills in the relevant fields. 


The FDL$RELEASE routine deallocates the virtual memory used by the RMS 
control blocks created by FDL6PARSE. 


These routines cannot be called from AST level. 


An FDL specification can be either in a file or in a character string. When 
specifying an FDL specification in a character string, delimit the statements of 
the FDL specification with semicolons. 





7.2 Examples of Using the FDL Routines 


Example 7-1 shows how to use the FDL$CREATE routine in a FORTRAN 
program. 
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Example 7-1 Using FDL$CREATE in a FORTRAN Program 


* e %* *¥ He Ke 


1000 
2000 


This program calls the FDL$CREATE routine. It 
creates an indexed output file named NEW_MASTER.DAT 
from the specifications in the FD1 file named 
INDEXED.FDL. You can also supply a default filename 
and a result name (that receives the name of the 
created file). The program also returns all the 
statistics... 


IMPLICIT INTEGER*4 (A - Z) 

EXTERNAL LIB$GET_LUN, FDL$CREATE 
CHARACTER IN_FILE*11 /‘ INDEXED.FDL'/, 

1 OUT_FILE*14 /'NEW_MASTER.DAT'/, 
1 DEF_FILE*11 /'DEFAULT.FDL'/, 

1 RES_FILE*50 

INTEGER*4 FIDBLK (3) /0,0,0/ 

T= 4 


STATUS = FDL$CREATE (IN_FILE,OUT_FILE, 
DEF _FILE,RES_FILE,FIDBLK, , ) 
IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS) ) 


STATUS=LIB$GET_LUN (LOG_UNIT) 
OPEN (UNIT=LOG_UNIT, FILE=RES_FILE, STATUS='OLD') 
CLOSE (UNIT=LOG_UNIT, STATUS='KEEP') 


WRITE (6,1000) (RES_FILE) 
WRITE (6,2000) (FIDBLK (I), I=1,3) 


FORMAT (1X, 'The result filename is: ',A50) 
FORMAT (/1X,'FID-NUM: ',I5/, 


4 1X, 'FID-SEQ: ',15/, 
4 1X,'FID-RVN: ',15) 
END : 
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Example 7-2 shows how to use the FDL$PARSE and FP Rel eee routines 


in a MACRO program. 


Example 7-2 Using FDL$PARSE and FDL$RELEASE in a MACRO 


Program 


; This program calls the FDL utility routines FDL$PARSE and 


; FDL$RELEASE. 
; PART.FDL. 
; using the primary key. 


.TITLE FDLEXAM 


.PSECT DATA,WRT,NOEXE 
MY_FAB: 
MY_RAB: 
FDL_FILE: 
REC_SIZE=80 
LF=10 
REC_RESULT : 


-LONG O 
-_LONG O 
.ASCID /PART.FDL/ , 


-LONG REC_SIZE 
.ADDRESS REC_BUFFER 
-BLKB REC_SIZE 
.ASCID /ID PART 


REC_BUFFER : 
HEADING: 


SUPPLIER 


.PSECT CODE 
; Declare the external routines 
. EXTRN FDL$PARSE, 
FDL$RELEASE 
. ENTRY FDLEXAM, “M<> : 
PUSHAL MY_RAB : 
PUSHAL MY_FAB : 
PUSHAL FDL_FILE ; 
CALLS #3,G°FDL$PARSE ; 
BLBS RO, KEYO 
BRW ERROR 
KEYO: MOVL 
MOVL 
MOVL 
MOVAB 
$OPEN FAB=(R10) ; 
BLBC RO, ERROR 
$CONNECT RAB=(R9) ; 
BLBC RO, ERROR 
PUSHAQ HEADING 
CALLS #1,G°LIB$PUT_OUTPUT 
BLBC RO, ERROR 


MY_FAB,R10 ; 
MY_RAB,R9 ; 


Example 7—2 Cont'd. on next page 


First, FDL$PARSE parses the FDL specification 
Then the data file named in PART.FDL is accessed 
Last, the control blocks allocated 
; by FDL$PARSE are released by FDL$RELEASE. 


Declare FDL file 


COLOR / 


Set up entry mask 

Get set up for call with 
addresses to receive the 
FAB and RAB allocated by 
FDL$PARSE 


Move address of FAB to R10 


Move address of RAB to R9 
#REC_SIZE , RAB$W_USZ (RQ) 
REC_BUFFER , RAB$L_UBF (R9) 


Open the file 


Connect to the RAB 


; Display the heading 
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Example 7-2 (Cont.) Using FDL$PARSE and FDL$RELEASE in a 


GET_REC: 


CLEAN : 


ERROR: 


RAB_ERROR : 


FAB_ERROR: 


RMS_ERR : 


FINI: 


MACRO Program 


$GET RAB= (RQ) ; Get a record 

CMPL #RMS$_EOF , RO ; If not end of file, 

BEQLU CLEAN ; continue 

BLBC RO , ERROR 

MOVZWL RAB$W_RSZ(R9),REC_RESULT ; Move a record into 

PUSHAL REC_RESULT ; the buffer 
‘CALLS  #1,G°LIB$PUT_OUTPUT ; Display the record 

BLBC RO , ERROR 

BRB GET_REC ; Get another record 

$CLOSE FAB=(R10) ; Close the FAB 

BLBC RO , ERROR 

PUSHAL MY_RAB ; Push RAB addr on stack 

PUSHAL MY_FAB ; Push FAB addr on stack 

CALLS #2 ,G*FDL$RELEASE ; Release control blocks 

BLBC RO , ERROR 

BRB FINI 

PUSHL RO 

CALLS #1,G°LIB$SIGNAL 

$CLOSE FAB=(R10) 

PUSHL  RAB$L_STV(R9) 

PUSHL RAB$L_STS(R9) 

BRB RMS_ERR 

PUSHL  FAB$L_STV(R10) 

PUSHL  FAB$L_STS(R10) 

CALLS #2,G°LIB$SIGNAL 

BRB FINI 

RET 

.END FDLEXAM 
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Example 7-3 shows how to use the FDL6GENERATE routine in a VAX Pascal 


program. 


Example 7-3 Using FDLSPARSE and FDL$GENERATE in a VAX 


Pascal Program 


[INHERIT ('SYS$LIBRARY : STARLET') ] 
PROGRAM FDLexample (input, output, order_master) ; 


(* This program fills in its own FAB, RAB, and 
(* XABs by calling FDL$PARSE and then generates 
(* an FDL specification describing them. 
(* It requires an existing input FDL file 
(« (TESTING.FDL) for FDL$PARSE to parse. 
TYPE 
(*+ 
(* FDL CALL INTERFACE CONTROL FLAGS 
(*- 
$BIT1 = [BIT(1) ,UNSAFE] BOOLEAN; 


FDL2$TYPE = RECORD CASE INTEGER OF 
1: (FDL$_FDLDEF_BITS : [BYTE(1)] RECORD END; 
Be 
2: (FDL$V_SIGNAL : [POS(0)] $BIT1; 
(* Signal errors; don't return 
FDL$V_FDL_STRING : [POS(1)] $BIT1; 
(* Main FDL spec is a char string 
FDL$V_DEFAULT_STRING : [POS(2)] $BIT1; 
(* Default FDL spec is a char string 
FDL$V_FULL_OUTPUT : [POS(3)] $BIT1; 
(* Produce a complete FDL spec 
FDL$V_$CALLBACK : [POS(4)] $BIT1; 


*) 
*) 
*) 
*) 
*) 


*) 
*) 
*) 


(* Used by EDIT/FDL on input (DEC only) *) 


) 
END; 


mail_order = RECORD Ff 
order_num : [KEY(0)] INTEGER; 


name : PACKED ARRAY[1..20] OF CHAR; 


address : PACKED ARRAY[1..20] OF CHAR; 


city : PACKED ARRAY{1..19] OF CHAR; 
state : PACKED ARRAY[1..2] OF CHAR; 


zip_code : [KEY(1)] PACKED ARRAY[1. .5] 


OF CHAR; 
item_num : [KEY(2)] INTEGER; 
shipping : REAL; 
END ; 


order_file = [UNSAFE] FILE OF mail_order; 
ptr_to_FAB = “FAB$TYPE; 
ptr_to_RAB = “RAB$TYPE; 
byte = 0..255; 

VAR 
order_master : order_file; 
flags : FDL2$TYPE; 
order_rec : mail_order; 
temp_FAB : ptr_to_FAB; 
temp_RAB : ptr_to_RAB; 
status : integer; 


Example 7—3 Cont'd. on next page 
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Example 7—3 (Cont.) Using FDL$PARSE and FDL$GENERATE in a 
VAX Pascal Program 


FUNCTION FDL$PARSE 
(ASTDESCR FDL_FILE : PACKED ARRAY [L..U: INTEGER] 
OF CHAR; 
VAR FAB_PTR : PTR_TO_FAB; 
VAR RAB_PTR : PTR_TO_RAB) : INTEGER; EXTERN; 


FUNCTION FDL$GENERATE 
(AREF FLAGS : FDL2$TYPE; 
FAB_PTR : PTR_TO_FAB; 
RAB_PTR : PTR_TO_RAB; 
%STDESCR FDL_FILE_DST : PACKED ARRAY [L..U: INTEGER] 
OF CHAR) : INTEGER; 
EXTERN ; 


BEGIN 


Status := FDL$PARSE ('TESTING' , TEMP_FAB, TEMP_RAB) 
flags::byte := 0; 
status := FDL$GENERATE (flags, 

temp_FAB, 

temp_RAB, 

'SYS$OUTPUT: '); 


END. 





7.3 FDL Routines 


The following pages describe the individual FDL routines. 


FDL—6 


File Definition Language (FDL) Routines 
FDL$CREATE 


FDL$CREATE Create a File from an FDL 
Specification and Close the File 


The FDL$CREATE routine creates a file from an FDL specification and then 
closes the file. 





FORMAT FDL$CREATE fd/_desc [, filename] [,default_name] 
[,result_name] [, fid_block] [, flags] 
[, stmnt_nur] [,retlen] [, sts] [,stv] 





RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS fdil_desc 
VMS usage: char_string 
type: character-coded text string 
access: read only 
mechanism: by descriptor—fixed-length string descriptor 


Name of a file that contains the FDL specification or the actual FDL 
specification to be parsed. The fdl_desc argument is the address of a 
character string descriptor pointing to this information. 


If the FDL$V_FDL_STRING flag is set in the mask argument, FDL$CREATE 
interprets this argument as an FDL specification in string form. Otherwise, 
FDL$CREATE interprets this argument as a file name. 


filename 

VMS usage: char_string 

type: character-coded text string 

access: read only 

mechanism: by descriptor—fixed-length string descriptor 


Name of the VMS RMS file to be created using the FDL specification. The 
filename argument is the address of a character string descriptor pointing to 
the VMS RMS file name. This name overrides the default_name parameter 
given in the FDL specification. 


This argument is optional. 
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default_name 

VMS usage: char_string 

type: character-coded text string 
access: read only 


mechanism: by descriptor—fixed-length string descriptor 


Default name of the file to be created using the FDL specification. The 
default_name argument is the address of a character string descriptor 
pointing to the default file name. This name overrides any name given in the 
FDL specification. 


This argument is optional. 


result_name 

VMS usage: char_string 

type: character-coded text string 

access: write only 

mechanism: by descriptor—fixed-length string descriptor 


Resultant name of the file created by FDL$CREATE. The result_name 
argument is the address of a character string descriptor that receives the 
resultant file name. 


This argument is optional. 


fid_block 

VMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: write only 


mechanism: by reference 


File identification of the VMS RMS file created by FDL$CREATE. The 
fid_block argument is the address of an array of longwords that receives 
the VMS RMS file identification information. The first longword contains 
the FID_NUM; the second contains the FID_SEQ; and the third contains the 
FID_RVN. They have the following definitions: 


FID_NUM The location of the file on the disk. Its value can range from 7 up 
to the number of files the disk can hold. 


FID_SEQ The file sequence number, which is the number of times the file 
number has been used. 


FID_RVN The relative volume number, which is the volume number of the 
volume on which the file is stored. If the file is not stored on a 
volume set, the relative volume number is 0. 


This argument is optional. 


flags 

VMS usage: mask—longword 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Flags (or masks) that control how the fdl_dese argument is interpreted and 
how errors are signaled. The flags argument is the address of a longword 
containing the control flags (or a mask). If you omit this argument or specify 
it as zero, no flags are set. The flags and their meanings are as follows: 
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Flag Description 


FDL$V_FDL_STRING Interprets the fdl_desc argument as an FDL 
specification in string form. By default, the fdl_desc 
argument is interpreted as the file name of an FDL file. 


FDL$V_SIGNAL Signals any error. By default, the status code is 
returned to the calling image. 


This argument is optional. By default, an error status is returned rather than 
signaled. 


stmnt_num 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


FDL statement number. The stmnt_num argument is the address of a 
longword that receives the FDL statement number. If the routine completes 
successfully, the stmnt_num argument is the number of statements in the 
FDL specification. If the routine does not complete successfully, the 
stmnt_num argument receives the number of the statement that caused 
the error. In general, however, line numbers and statement numbers are 
not the same. Null statements (blank lines) are not counted. Also, an FDL 
specification in string form has no “lines.” 


This argument is optional. 


retlen 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 


mechanism: by reference 


Number of characters returned in the result_name argument. The retlen 
argument is the address of a longword that receives this number. 


This argument is optional. 


sts 

VMS usage: longword_unsigned 
type: longword_unsigned 
access: write only 


mechanism: by reference 


VMS RMS status value FAB$L_STS. The sts argument is the address of 
a longword that receives the VMS RMS status value FAB$L_STS from 
SYS$CREATE. 


stv 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 


mechanism: by reference 


VMS RMS status value FAB$L_STV. The stv argument is the address of 
a longword that receives the VMS RMS status value FAB$L_STV from 
SYS$CREATE. 
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FDLSCREATE 

DESCRIPTION — FDLSCREATE calls the FDL$PARSE routine to parse the FDL specification. 

The FDL specification can be either in a file or a character string. 
FDL$CREATE opens (creates) the specified VMS RMS file, and then closes it 
without putting any data in it. 
FDL$CREATE does not create the output file if an error status is either 
returned or signaled. 

CONDITION SS$_NORMAL N | ful leti 

Mla Ack FDLS. ABKW pets ieee ane = t 

RETURNED = mbiguous keyword in statement n. 


FDL-—10 


FDL$_ABPRIKW 
FDL$_BADLOGIC 
FDL$_CLOSEIN 
FDL$_CLOSEOUT 
FDL$_CREATE 
FDL$_CREATED 
FDL$_CREATED_STM 
FDL$_FDLERROR 
FDL$_ILL__ARG 
FDL$_INSVIREM 
FDL$_INVBLK 


FDL$_MULPRI 
FDL$_OPENFDL 
FDL$_OPENIN 
FDL$_OPENOUT 
FDL$_OUTORDER 


FDL$_READERR 
FDL$_RFLOC 
FDL$_SYNTAX 
FDL$_UNPRIKW 
FDL$_UNQUAKW 
FDL$_UNSECKW 
FDL$_VALERR 
FDL$_VALPRI 
FDL$_WARNING 
FDL$_WRITEERR 
RMS$_ACT 
RMS$_CRE 
RMS$_CREATED 


Ambiguous primary keyword in statement n. 
Internal logic error detected. 

Error closing file specification as input. 

Error closing file specification as output. 
Error creating file specification. 

File specification created. 

File specification created in stream format. 
Error parsing FDL file. 

Wrong number of arguments. 

Insufficient virtual memory. 


Invalid VMS RMS control block at virtual 
address n. 


Multiple primary definition in statement n. 
Error opening file specification. 

Error opening file specification as input. 
Error opening file specification as output. 


Key or area primary defined out of order in 
statement n. 


Error reading file specification. 

Unable to locate related file. 

Syntax error in statement n. 

Unrecognized primary keyword in statement n. 
Unrecognized qualifier keyword in statement n. 
Unrecognized secondary keyword in statement n. 
Specified value is out of legal range. 

Value required on primary in statement n. 
Parsed with warnings. 

Error writing file specification. 

File activity precludes operation. 

ACP file create failed. 


File was created, not opened. 
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RMS$_DNF Directory not found. 
RMS$_DNR Device not ready or not mounted. 
RMS$_EXP File expiration date not yet reached. 
RMS$_FEX File already exists, not superseded. 
RMS$_FLK File currently locked by another user. 
RMS$_PRV Insufficient privilege or file protection violation. 
RMS$_SUPERSEDE Created file superseded existing version. 
RMS$_WLK Device currently write locked. 
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FDL$GENERATE Generate an FDL Specification 


The FDL$GENERATE routine produces an FDL specification and writes it 
to either an FDL file or a character string. 





FORMAT | FDL$GENERATE _ flags ,fab_pointer ,rab_pointer 
[,fdl_file_dst] [,fdl_file_resnam] 
[,fdl_str_dst] [,bad_blk_adadr] [,retlen] 





RETURNS VMS usage: cond_value : 
type: longword (unsigned) - 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS flags 7 _ 
VMS. usage: mask—longword 
type: | longword (unsigned) 
access: —_—srread only . 
mechanism: by reference 


Flags (or masks) that control how the fdl_str_dst argument is interpreted and 
how errors are signalled. The flags argument is the address of a longword 
containing the control flags (or a mask). If you omit this argument or specify 
it as zero, no flags are set. The flags and their meanings are as follows: 


Flag Description 


FDL$V_FDL STRING Interprets the fdl_str_dst argument as an FDL 
specification in string form. By default, the fdl_str_ 
dst argument is interpreted as a file name of an FDL 
file. 


FDL$V_FULL _OUTPUT Includes the FDL attributes to describe all the bits 
and fields in the VMS RMS control blocks, including 
run-time options. If this flag is set, every VMS RMS 
field is inspected before being written. By default, 
only the FDL attributes that describe permanent file 
attributes are included (producing a much shorter FDL 
specification). 


FDL$V_SIGNAL Signals any error. By default, the status code is 
returned to the calling image. 


This argument is optional. By default, an error status is returned rather than 
signaled. 
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fab_pointer 


VMS usage: address 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


VMS RMS file access block (FAB). The fab_pointer argument is the address 
of a longword containing the address of a VMS RMS file access block (FAB). 


rab_pointer 

VMS usage: address 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


VMS RMS record access block (RAB). The rab_pointer argument is the 
address of a longword containing the address of a VMS RMS record access 
block (RAB). 


fdl_file_.dst 


VMS usage: char_string 

type: character-coded text string 
access: read only 

mechanism: by descriptor 


Name of the FDL file to be created. The fdl_file_dst argument is the address 
of a character string descriptor containing the file name of the FDL file to be 
created. If the FDL$V_FDL_STRING flag is set in the flags argument, this 
argument is ignored; otherwise, it is required. The FDL specification is written 
to the file named in this argument. 


fdl_file_resnam 

VMS usage: char_string 

type: character-coded text string 

access: write only 

mechanism: by descriptor—-fixed-length string descriptor 


Resultant name of the FDL file created. The fdl_file_resnam argument is 
the address of a variable character string descriptor that receives the resultant 
name of the FDL file created (if FDLSGENERATE is directed to create an FDL 
file). 


This argument is optional. 


fdl_str_dst 

VMS usage: char_string 

type: character-coded text string 
access: write only 


mechanism: by descriptor—fixed-length string descriptor 


FDL specification. The fdl_str_dst argument is the address of a variable 
character string descriptor that receives the FDL specification created. If 
the FDL$V_FDL_STRING bit is set in the flags argument, this argument is 
required; otherwise, it is ignored. 
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bad_blk_addr 


VMS usage: address 

type: longword (unsigned) 
access: write only 
mechanism: by reference 


Address of an invalid VMS RMS control block. The bad_blk—addr argument 
is the address of a longword that receives the address of an invalid VMS 
RMS control block. If an invalid control block (a fatal error) is detected, this 
argument is returned; otherwise, it is ignored. 


This argument is optional. 


retlen 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


Number of characters received in either the fdl_file_resnam or the 
fdl_str_dst argument. The retlen argument is the address of a longword 


that receives this number. 





CONDITION 
VALUES 
RETURNED 
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SS$_NORMAL 
FDL$_INVBLK 


RMS$_ACT 
RMS$_CONTROLC 
RMS$_CONTROLO 
RMS$_CONTROLY 
RMS$_DNR 
RMS$_EXT 
RMS$_OK_ALK 
RMS$_OK_DUP 
RMS$_OK_IDX 
RMS$_PENDING 
RMS$_PRV 
RMS$_REX 
RMS$_RLK 
RMS$_RSA 
RMS$_WLK 
SS$_ACCVIO 
STR$_FATINERR 
STR$_ILLSTRCLA 
STR$_INSVIRMEM 


Normal successful completion. 


Invalid VMS RMS control block at virtual 
address n. 


File activity precludes operation. 

Operation completed under CTRL/C. 

Output completed under CTRL/O. 

Operation completed under CTRL/Y. 

Device not ready or mounted. 

ACP file extend failed. 

Record already locked. 

Record inserted had duplicate key. 

Index update error occurred. 

Asynchronous operation pending completion. 
Insufficient privilege or file protection violation. 
Record already exists. 

Target record currently locked by another stream. 
Record stream currently active. 

Device currently write locked. 

Access violation. 

Fatal internal error in Run-Time Library. 

Illegal string class. 

Insufficient virtual memory. 


File Definition Language (FDL) Routines 
FDLS$PARSE 


-FDL$PARSE Parse an FDL Specification 


The FDL$PARSE routine parses an FDL specification, allocates VMS RMS 
control blocks (FABs, RABs, or XABs), and fills in the relevant fields. 





FORMAT 


FDL$PARSE  fd/_spec ,fdl_fab_pointer 
,tdl_rab_pointer [, flags] [,dflt_fdl_spc] 
[,stmnt_num] 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


fdl_spec 

VMS usage: char_string 

type: character-coded text string 

access: read only 

mechanism: by descriptor—fixed-length string descriptor 


Name of the FDL file or the actual FDL specification to be parsed. The 
fdl_spec argument is the address of a character string descriptor pointing to 
either the name of the FDL file or the actual FDL specification to be parsed. 
If the FDL$V_FDL_STRING flag is set in the flags argument, FDL$PARSE 
interprets this argument as an FDL specification in string form. Otherwise, 
FDL$PARSE interprets this argument as a file name of an FDL file. 


fdl_fab_pointer 

VMS usage: address 

type: longword (unsigned) 
access: write only 
mechanism: by reference 


Address of an RMS file access block (FAB). The fdl_fab_pointer argument 
is the address of a longword that receives the address of an RMS file access 
block (FAB). FDL$PARSE both allocates the FAB and fills in its relevant fields. 


fdl_rab_pointer 

VMS usage: address 

type: longword (unsigned) 
access: write only 
mechanism: by reference 


Address of an RMS record access block (RAB). The fdl_rab_pointer 
argument is the address of a longword that receives the address of an RMS 
record access block (RAB). FDL$PARSE both allocates the RAB and fills in its 
relevant fields. . 
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flags 

VMS usage: mask—longword 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Flags (or masks) that control how the dflt_fdl_spc argument is interpreted 
and how errors are signaled. The flags argument is the address of a longword 
containing the control flags. If you omit this argument or specify it as zero, 
no flags are set. The flags and their meanings are as follows: 


Flag Description 


FDL$V_DEFAULT_STRING interprets the dflt_fdl_spe argument as an FDL 
specification in string form. By default, the 
dfilt_fdl_spc argument is interpreted as a file 
name of an FDL file. 


FDL$V_FDL_STRING Interprets the fdl_spec argument as an FDL 
specification in string form. By default, the 
fdl_spec argument is interpreted as a file name 
of an FDL file. 


FDL$V_SIGNAL . Signals any error. By default, the status code is 
returned to the calling image. 


This argument is optional. By default, an error status is returned rather than 
signaled. 


dfilt_fdl_spc 


VMS usage: char_string 

type: character-coded text string 

access: read only 

mechanism: by descriptor—fixed-length string descriptor 


Name of the default FDL file or the default FDL specification itself. The 
dflt_fdl_spce argument is the address of a character string descriptor pointing 
to either the default FDL file or the default FDL specification. If the 
FDL$V_DEFAULT_STRING flag is set in the flags argument, FDL$PARSE 
interprets this argument as an FDL specification in string form. Otherwise, 
FDL$PARSE interprets this argument as a file name of an FDL file. 


This argument allows you to specify default FDL attributes. In other words, 
FDL$PARSE processes the attributes specified in this argument, unless you 
override them with the attributes you specify in the fdl_spec argument. 


You can code the FDL defaults directly into your program, typically with an 
FDL specification in string form. 


This argument is optional. 
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stmnt_num 


VMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


FDL statement number. The stmnt_num argument is the address of a 
longword that receives the FDL statement number. If the routine completes 
successfully, the stmnt_num argument is the number of statements in the 
FDL specification. If the routine does not complete successfully, the 
stmnt_num argument receives the number of the statement that caused the 
error. In general, however, line numbers and statement numbers are not the 
same. 


This argument is optional. By default, an error status is returned rather than 





signaled. 
CONDITION | 
VALU ES SS$_NORMAL Normal successful completion. 
RETURNED LIB$_BADBLOADR Bad block paneer: 
LIB$_BADBLOSIZ Bad block size. 
LIB$_INSVIRMEM Insufficient virtual memory. 
RMS$_DNF Directory not found. 
RMS$_DNR Device not ready or not mounted. 
RMS$_WCC Invalid wildcard context (WCC) value. 
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FDL$RELEASE Free Virtual Memory Obtained By 


FDL$PARSE 


The FDL$RELEASE routine deallocates the virtual memory used by 
the VMS RMS control blocks created by FDL$PARSE. You must use 
FDL$PARSE to populate the control blocks if you plan to deallocate 
memory with FDL$RELEASE later. 





FORMAT 


FDLSRELEASE /fab_pointer] [,rab_pointer] [, flags] 
[,badblk_adadr] 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 
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fab_pointer 

VMS usage: address 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


File access block (FAB) to be deallocated using the LIB{FREE_VM system 
service. The fab_pointer argument is the address of a longword containing 
the address of the file access block (FAB). The FAB must be the same one 
returned by the FDL$PARSE routine. Any name blocks (NAMs) and extended 
attribute blocks (XABs) connected to the FAB are also released. 


This argument is optional. If you omit this argument or specify it as zero, the 
FAB (and any associated NAM blocks and XABs) is not released. 


rab_pointer 

VMS usage: address 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Record access block (RAB) to be deallocated using the LIB}FREE_VM system 
service. The rab_pointer argument is the address of a longword containing 
the address of the record access block (RAB). The address of the RAB must be 
the same one returned by the FDL$PARSE routine. Any XABs connected to 
the RAB are also released. 


This argument is optional. If you omit this argument or specify it as zero, the 
RAB (and any associated XABs) is not released. — 
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flags 
VMS usage: mask—longword 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Flag (or mask) that controls how errors are signalled. The flags argument 
is the address of a longword containing the control flag (or a mask). If you 
omit this argument or specify it as zero, no flag is set. The flag is defined as 
follows: 


FDL$V_SIGNAL Signals any error. By default, the status code is returned to 
the calling image. 


This argument is optional. 


badblk_addr 


VMS usage: address 

type: longword (unsigned) 
access: write only 
mechanism: by reference 


Address of an invalid VMS RMS control block. The badblk_addr argument 
is the address of a longword that receives the address of an invalid VMS 


~ RMS control block. If an invalid control block (a fatal error) is detected, this 


argument is returned; otherwise, it is ignored. 





CONDITION 
VALUES _ 
RETURNED 


SS$_NORMAL Normal successful completion. 
FDL$_INVBLK Invalid VMS RMS control block at virtual 
address n. 

LIB$__BADBLOADR Bad block address. 

RMS$_ACT File activity precludes operation. 
RMS$_RNL Record not locked. 

RMS$_RSA Record stream currently active. 
SS$_ACCVIO Access violation. 
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Introduction to LBR Routines 


Libraries are files that provide a convenient way to organize frequently used 
modules of code or text. The librarian routines allow you to create and 
maintain libraries and their modules and to use the data stored in library 
modules. . 


You can also create and maintain libraries at the DCL level, using the DCL 
command LIBRARY. For details, see the VMS DCL Dictionary. 


Types of Library 
You can use the librarian routines to maintain the following types of library: 


¢ Object libraries, which contain the object modules of frequently called 
routines. The VMS Linker Utility searches specified object module 
libraries when it encounters a reference it cannot resolve in one of its 
input files. For more information about how the linker uses libraries, 
see the description of the VMS Linker Utility in the VMS Linker Utility 
Manual. 


An object library has a default file type of OLB and defaults the file type 
of input files to OBJ. 


¢ Macro libraries, which contain macro definitions used as input to the 
assembler. The assembler searches specified macro libraries when it 
encounters a macro that is not defined in the input file. See the VAX 
MACRO and Instruction Set Reference Manual for information about 
defining macros. 


A macro library has a default file type of MLB and defaults the file type 
of input files to MAR. 


e Help libraries, which contain modules of help messages that provide 
user information about a program. You can retrieve help messages at 
DCL level by executing the DCL command HELP, or in your program by 
calling the appropriate librarian routines. For information about creating 
help modules for insertion into help libraries, see the description of the 
Librarian Utility in the VMS Librarian Utility Manual. 


A help library has a default file type of HLB and defaults the file type of 
input files to HLP. 


e Text libraries, which contain any sequential record files that you want to 
retrieve as data for a program. For example, some compilers can retrieve 
program source code from text libraries. Each text file inserted into the 
library corresponds to one library module. Your programs can retrieve 
text from text libraries by calling the appropriate librarian routines. 


A text library has a default file type of TLB and defaults the file type of 
input files to TXT. 
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e Shareable image libraries, which contain the symbol tables of shareable ~ 
images used as input to the linker. For information about how to create a 
shareable image library, see the descriptions of the Librarian and Linker 
Utilities in the VMS Librarian Utility Manual and the VMS Linker Utility 
Manual. 


A shareable image library has a default type of OLB and defaults the file 
type of input files to EXE. 


e¢ User-developed libraries, which have characteristics specified when you 


call the LBR$OPEN routine to create a new library. User-developed 
libraries allow you to use the librarian routines to create and maintain 
libraries that are not structured in the form assigned by default to 
the other library types. Note that you cannot use the DCL command 
LIBRARY to access user-developed libraries. 


8.1.2 Structure of Libraries 
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8.1.2.2 


8.1.2.3 


You create libraries by executing the DCL command LIBRARY or by calling 
the LBR$60PEN routine. When object, macro, text, help, or shareable image 
libraries are created, the Librarian Utility structures them as described in 
Figures 8-1 and 8-2. You can create user-developed libraries only by calling 
LBRS$SOPEN; they are structured as described in Figure 8-3. 


Library Headers 


Every library contains a library header that describes the contents of the 
library, for example, its type, size, version number, creation date, and number 
of indexes. You can retrieve data from a library’s header by calling the 
LBR$GET_HEADER routine. 


Modules 

Each library module consists of a header and data. The data is the data you 
inserted into the library; the header associated with the data is created by 
the librarian routine and provides information about the module, including 


its type, attributes, and date of insertion into the library. You can read and 
update a module’s header by calling the LBR$SET_MODULE routine. 


Indexes and Keys 

Libraries contain one or more indexes, which can be thought of as directories 
of the library’s modules. The entries in each index are keys, and each key 
consists of a key name and a module reference. The module reference is a 
pointer to the module’s header record and is called that record’s file address 
(RFA). Macro, text, and help libraries (see Figure 8-1) contain only one index, 
called the module name table. The names of the keys in the index are the 
names of the modules in the library. 


Object and shareable image libraries (see Figure 8-2) contain two indexes: 
the module name table and a global symbol table. The global symbol table 
consists of all the global symbols defined in the modules in the library. Each 
global symbol is a key in the index and points to the module in which it was 
defined. 


If you need to point to the same module with several keys, you should create 
a user-developed library, which can have up to eight indexes (see Figure 8-3). 
Each index consists of keys that point to the library’s modules. 
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starting with 1.| For all but user-developed libraries, the module name table is 
index number 1\ and the global symbol table, if present, is index 

number 2. You number the indexes in user-developed libraries. When you 
access libraries that contain more than one index, you may have to call 
LBR$SET_INDEX to tell the librarian routines which index to use. 


The librarian ae differentiate library indexes by numbering them, 


Figure 8—1 Structure of a Macro, Text, or Help Library 






library header 









index (module name table) 


Each key in the index points to a module. 






modules 
data data data data 
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Figure 8—2 Structure of an Object or Shareable Image Library 











library header 





index (module name table) 


Each key in the index points to a module. 





index (global symbol table) 


global global global global global 
symbol symbol symbol symbol symbol 


Each global symbol is a key in the index, and points to the module in 
which it was defined. 





modules 


data data data 
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Figure 8-3 Structure of a User-Developed Library 
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index 


Each key in an index points to one module. More than one key (from 
the same or a different index) may point to the same module. 


Can have up to 
8 indexes. 
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8.1.2.4 


Summary of Routines 

All the librarian routines begin with the characters LBR$. Your programs 
can call these routines by using the VMS Procedure Calling and Condition 
Handling Standard, which is documented in the Introduction to VMS System 
Routines. When you call a librarian routine, you must provide whatever 
arguments the routine requires; when the routine completes execution, it 
returns a status value to your program. In addition to the condition values 
listed with the descriptions of each routine, some routines may return the 
success code SS$¢_NORMAL as well as various RMS or SS error codes. When 
you link programs that contain calls to librarian routines, the linker locates 
the routines during its default search of SYS$SHARE:LBRSHR. 


The following table lists the routines and summarizes their functions. 


Routine Name 


LBRSCLOSE 
LBRSDELETE_DATA 
LBRSDELETE_KEY 
LBRSFIND 


LBRSFLUSH 


LBRSGET_HEADER 


LBRSGET_HELP 
LBRSGET_HISTORY 


LBR$GET_INDEX 


LBRSGET_RECORD 


LBRSINI_CONTROL 


LBRSINSERT_KEY 
LBRSLOOKUP_KEY 
LBRSOPEN 
LBRSOUTPUT_HELP 


LBRSPUT_END 


LBRSPUT_HISTORY 
LBR$PUT_RECORD 


LBRSREPLACE_KEY 
LBRSRET_RMSSTV 


Function 


Closes an open library. 
Deletes a specified module’s header and data. 
Deletes a key from a library index. 


Finds a module by using an address returned by a 
preceding call to LBR6LOOKUP_KEY. 


Writes the contents of modified blocks to the library 
file and returns the virtual memory that contained those 
blocks. 


Retrieves information from the library header. 
Retrieves help text from a specified library. 


Retrieves library update history records and calls a 
user-supplied routine with each record returned. 


Calls a routine to process modules associated with some 
or all of the keys in an index. 


Reads a data record from the module associated with a 
specified key. 


Initializes a control index that the librarian uses to 
identify a library. 


Inserts a new key in the current library index. 
Looks up a key in the current index. 
Opens an existing library or creates a new one. 


Retrieves help text from an explicitly named library 
or from user-supplied default libraries, and optionally 
prompts you for additional help queries. 


Terminates a sequence of records written to a module 


- with LBRGPUT_RECORD. 


Inserts a library update history record. 


Writes a data record to the module associated with the 
specified key. 


Replaces an existing key in the current library index. 
Returns the last VMS RMS status value. 


Librarian (LBR) Routines 
8.1 Introduction to LBR Routines 


Routine Name Function 

LBR$SSEARCH Finds index keys that point to specified data. 

LBRSSET_INDEX Sets the index number to be used during processing of 
the library. 

LBRSSET_LOCATE Sets librarian subroutine record access to locate mode. 

LBR$SET_MODULE Reads and optionally updates a module header. 

LBR$SET_MOVE Sets librarian subroutine record access to move mode. 





8.2 Examples of Using the LBR Routines 


This section provides programming examples that show how to call LBR$ 
routines to create a library, insert a module into a library, extract a module 
from a library, and delete a module from a library. Although the examples 
do not use all of the librarian routines, they do provide an introduction to 
the data structures needed and the calling syntax required to use any of the 
routines. 


For each library you want to work with, you must call LBR$INI_-CONTROL 
and LBR$OPEN before calling any other routine (except 
LBR6OUTPUT_HELP). 


When you call LBR$INI_CONTROL, this routine sets up a control index (do 
not confuse this with a library index) that is used, in the calls to the other 
librarian routines, to identify the library to which the routine applies (because 
you may want your program to work with more than one library at a time). 
LBR$INI_CONTROL also specifies whether you want to create, read, or 
modify the library. 


After you call LBR$INI_CONTROL, you call LBRSOPEN to open the 
library and specify its type. When you finish working with a library, you 
should call LBR$CLOSE to close it. Remember to call LBR$INI-CONTROL 
again, if you want to reopen the library. LBR$CLOSE deallocates all the 
memory associated with the library including the control index. The order in 
which you call the routines between LBR6OPEN and LBR$CLOSE depends 
upon the library operations you need to perform. You may want to call 
LBR$LOOKUP_KEY or LBR$GET_INDEX to find a key, then perform some 
operation on the module associated with the key. You can think of a module 
as being both the module itself and its associated keys. To access a module, 
you first need to access a key that points to it; to delete a module, you first 
need to delete any keys that point to it. 


The examples are written in VAX Pascal. In VAX Pascal, all data items, 
functions (such as the librarian routines), and procedures must be declared at 
the beginning of the program. Following the declarations is the executable 
section, which performs the actions of the program. The executable section 
makes extensive use of the structured control constructs IF-THEN-ELSE and 
WHILE-condition-DO. Note that code between a BEGIN END pair is treated 
as a unit. 


The listing of each example contains many comments (any code between a 
pair of asterisks (* *) is a comment), and each listing is followed by notes 
about the program. The highlighted numbers in the notes are keyed to the 
highlighted numbers in the examples. 
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Example 8-1 illustrates the use of LBR routines to create a new library. 


Example 8—1 Creating a New Library Using VAX Pascal 


PROGRAM createlib(INPUT, OUTPUT) ; 
(*This program creates a text library*) 


TYPE (*Data type of*) 
Create_Array = ARRAY [1..20] OF INTEGER; (*create options array*) 
VAR (*Constants and return status error 


codes for LBR$_OPEN & LBR$INI_CONTROL. 
These are defined in $LBRDEF macro*) 
LBR$C_CREATE, LBR$C_TYP_TXT , LBR$_ILLCREOPT , LBR$_ILLCTL, 
LBR$_ILLFMT , LBR$_NOFILNAM, LBR$_OLDMISMCH,LBR$_TYPMISMCH : 
[EXTERNAL] INTEGER; 
(*Create options array codes. These 
are defined in $CREDEF macro*) 
CRE$L_TYPE, CRE$L_KEYLEN , CRE$L_ALLOC , CRE$L_IDXMAX,CRE$L_ENTALL, @ 
CRE$L_LUHMAX , CRE$L_VERTYP , CRE$L_IDXOPT , CRE$C_MACTXTCAS , 


CRE$C_VMSV3 : [EXTERNAL] INTEGER ; 

Lib_Name : VARYING [128] OF CHAR; (*Name of library to create*) 

Options : Create_Array; (*Create options array*) 

File_Type : PACKED ARRAY [1..4] (*Character string that is default*) 
OF CHAR := '.TLB'; (*file type of created lib file*) 

lib_index_ptr : UNSIGNED; («Value returned in library init*) 

status : UNSIGNED; (*Return Status for function calls*) 


(*-*-*-*-Function and Procedure Definitions-*-*-*-*) 
(*Function that returns library 
control index used by librarian*) 
FUNCTION LBR$INI_CONTROL (VAR library_index: UNSIGNED; 3 
func: UNSIGNED; 
typ: UNSIGNED; 
VAR namblk: ARRAY[1..u: INTEGER] 
OF INTEGER := %IMMED 0): 
INTEGER; EXTERN; 
(*Function that creates/opens library*) 
FUNCTION LBR$OPEN (library_index: UNSIGNED; 
fns: [class_s]PACKED ARRAY[1..u: INTEGER] OF CHAR; 
create_options: Create_Array ; 
dns: [CLASS_S] PACKED ARRAY [13..u3: INTEGER] OF CHAR; 
rlfna: ARRAY [14..u4:INTEGER] OF INTEGER := %IMMED 0; 
rns: [CLASS_S] PACKED ARRAY [15..u5:INTEGER] OF CHAR := 
%IMMED 0; 
VAR rnslen: INTEGER := %IMMED 0): 
INTEGER; EXTERN; 
(*Function that closes library*) 
FUNCTION LBR$CLOSE (library_index: UNSIGNED) : 
INTEGER; EXTERN; 
(*Error handler to check error codes 
if open/create not successful*) 





Example 8—1 Cont'd. on next page 
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Example 8—1 (Cont.) Creating a New Library Using VAX Pascal 


PROCEDURE Open_Error; 4) 


BEGIN 
WRITELN('Open Not Successful'); (*Now check specific error codes*) 
IF status = IADDRESS(LBR$_ILLCREOPT) THEN 
WRITELN (' Create Options Not Valid Or Not Supplied’) ; 
IF status = IADDRESS(LBR$_ILLCTL) THEN 
WRITELN (' Invalid Library Index'); 
IF status = IADDRESS(LBR$_ILLFMT) THEN 
WRITELN (' Library Not In Correct Format'); 
IF status = IADDRESS(LBR$_NOFILNAM) THEN 
WRITELN (' Library Name Not Supplied'); 
IF status = IADDRESS(LBR$_OLDMISMCH) THEN 
WRITELN (' Old Library Conflict'); 
IF status = IADDRESS(LBR$_TYPMISMCH) THEN 
WRITELN (' Library Type Mismatch') 
END; (*of procedure Open_Error*) 


BEGIN (+ 2K DECLARATIONS COMPLETE oO ROO KEK 


END. 


AoE MATIN PROGRAM BEGINS: HERE 2 eo ode GK >) 
(*Prompt for Library Name*) 
WRITE('Library Name: '); READLN(Lib_Name) ; 
(*Fill Create Options Array. Divide 
by 4 and add 1 to get proper subscript*) 
Options [IADDRESS(CRE$L_TYPE) DIV 4 + 1] IADDRESS (LBR$C_TYP_TXT) ; 


Options [IADDRESS(CRE$L_VERTYP) DIV 4 + 1] IADDRESS (CRE$C_VMSV32) ; 
Options [IADDRESS(CRE$L_IDXOPT) DIV 4 + 1] IADDRESS (CRE$C_MACTXTCAS) ; 

(«Initialize library control index*) 
status := LBR$INI_CONTROL (lib_index_ptr, 


Options [IADDRESS(CRE$L_KEYLEN) DIV 4 + 1] := 31; 
Options [IADDRESS(CRE$L_ALLOC) DIV 4 + 1] = 8; 
Options [IADDRESS(CRE$L_IDXMAX) DIV 4 + 1] := 1; 
Options [IADDRESS(CRE$L_ENTALL) DIV 4 + 1] := 96; 
Options [IADDRESS (CRE$L_LUHMAX) DIV 4 + 1] := 20; 


IADDRESS (LBR$C_CREATE) , (*Create access*) 
IADDRESS(LBR$C_TYP_TXT)); (*Text library*) 
IF NOT ODD(status) THEN (*Check return status*) 
WRITELN('Initialization Failed') 
ELSE (*Initialization was successful*) 
BEGIN (*Create and open the library*) 
status := LBR$OPEN (lib_index_ptr, 
Lib_Name, 
Options, 7) 
File_Type) ; 
IF NOT ODD(status) THEN (*Check return status*) 
Open_Error (*Call error handlerx) © 
ELSE (*Open/create was successful*) 
BEGIN (*Close the library*) 


status := LBR$CLOSE(lib_index_ptr) ; 
IF NOT ODD(status) THEN (*Check return status*) 
WRITELN('Close Not Successful') 
END 
END 
(*of program creatlib*) 
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LBR—10 


Each item in the following list corresponds to a number highlighted in 
Example 8-1. ; 


3) 


To gain access to these LBR$ symbols in your program, write the 
following two-line MACRO program: 


$LBRDEF GLOBAL 
.END 


Then assemble the program into an object module by executing the 
command: 


MACRO program-name 


Finally, link the resultant object module with the object module created 
when your source program is compiled or assembled. (Note: Pascal 
programmers alternatively may use the INHERIT attribute to include 
these symbols from SYS$LIBRARY:STARLET.PEN.) 


To gain access to the CRE$ symbols, write a two-line MACRO program 
as described in item 1, substituting $CREDEF for $LBRDEF. 


Start the declarations of the librarian routines that are used by the 
program. Each argument to be passed to the librarian is specified on a 
separate line and includes the name (which just acts as a placeholder) and 
data type (for example: UNSIGNED, which means an unsigned integer 


‘value, and PACKED ARRAY OF CHAR, which means a character string). 


If the argument is preceded by VAR, then a value for that argument is 
returned by the librarian to the program. 


Declare the procedure Open_—Error, which is called in the executable 
section if the librarian returns an error when LBR$OPEN is called. 
Open_Error checks the librarian’s return status value to determine the 
specific cause of the error. The return status values for each routine are 
listed in the descriptions of the routines. 


Initialize the array called Options with the values the librarian needs to 
create the library. 


Call LBR$INI_CONTROL, specifying that the function to be performed is 
create and that the library type is text. 


Call LBR$OPEN to create and open the library; pass the Options array 
initialized in item 5 to the librarian. 


If the call to LBR$0PEN was unsuccessful, call the procedure 
Open_Error (see item 4) to determine the cause of the error. 


Example 8-2 illustrates the use of LBR routines to insert a new module into a 
library. 


Librarian (LBR) Routines 
8.2 Examples of Using the LBR Routines 


Example 8—2_ Inserting a Module Into a Library Using VAX Pascal 





PROGRAM insertmod (INPUT, OUTPUT) ; 
(*This program inserts a module into a library*) 


TYPE 
Rfa_Ptr = ARRAY [0..1] OF INTEGER; («Data type of RFA of module*) 
VAR 
LBR$C_UPDATE, (*Constants for LBR$INI_CONTROL*) 
LBR$C_TYP_TXT, (*Defined in $LBRDEF macro*) 


LBR$_KEYNOTFND : [EXTERNAL] INTEGER; (*Error code for LBR$LOOKUP_KEY*) 
Lib_Name : VARYING [128] OF CHAR; (*Name of library receiving module*) 
Module_Name : VARYING [31] OF CHAR; (*Name of module to insert*) 
Text_Data_Record : VARYING [255] OF CHAR; (*Record in new module*) 
Textin : FILE OF VARYING [255] OF CHAR; (*File containing new module*) 


lib_index_ptr : UNSIGNED; (*Value returned in library init*) 
status : UNSIGNED; (*Return status for function calls*) 
txtrfa_ptr : Rfa_Ptr; (*For key lookup and insertion*) 


Key_Not_Found : BOOLEAN := FALSE; (*True if new mod not already in lib*) 
(*-*-*-*-Function Definitions-*-*-*-*) 
(*Function that returns library 
control index used by librarian*) 
FUNCTION LBR$INI_CONTROL (VAR library_index: UNSIGNED; 
func: UNSIGNED; 
typ: UNSIGNED; 
VAR namblk: ARRAY[1..u: INTEGER] 
OF INTEGER := %IMMED 0): 
INTEGER; EXTERN; 
(*Function that creates/opens library*) 
FUNCTION LBR$OPEN (library_index: UNSIGNED; 
fns: [class_s]PACKED ARRAY(1..u:INTEGER] OF CHAR; 
create_options: ARRAY [12..u2:INTEGER] OF INTEGER := 
“%IMMED 0; 
dns: [CLASS_S] PACKED ARRAY [13..u3: INTEGER] OF CHAR 
:= %IMMED 0; 
rlfna: ARRAY [14..u4:INTEGER] OF INTEGER := %IMMED 0; 
rns: [CLASS_S] PACKED ARRAY [15..u5: INTEGER] OF CHAR := 
%IMMED 0; 
VAR rnslen: INTEGER := %IMMED 0): 
INTEGER; EXTERN; 
(*Function that finds a key in index*) 
FUNCTION LBR$LOOKUP_KEY (library_index: UNSIGNED; 
key_name: [CLASS_S] PACKED ARRAY [1..u: INTEGER] OF 
CHAR; 
VAR txtrfa: Rfa_Ptr): 
INTEGER; EXTERN ; 
(*Function that inserts key in index*) 
FUNCTION LBR$INSERT_KEY (library_index: UNSIGNED; 
key_name:[CLASS_S] PACKED ARRAY [1..u: INTEGER] OF 
CHAR; 
txtrfa: Rfa_Ptr): 
INTEGER; EXTERN; 
(*Function that writes data records*) 





Example 8—2 Cont'd. on next page 
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Example 8—2 (Cont.) Inserting a Module Into a Library Using VAX Pascal 


FUNCTION LBR$PUT_RECORD (library_index: UNSIGNED; (*to modules*) 
textline: [CLASS_S] PACKED ARRAY [1..u: INTEGER] OF 
CHAR; 


txtrfa: Rfa_Ptr): 
INTEGER; EXTERN; 
(«Function that marks end of a module) 
FUNCTION LBR$PUT_END (library_index: UNSIGNED) : 
INTEGER; EXTERN; 
(*Function that closes library*) 
FUNCTION LBR$CLOSE (library_index: UNSIGNED): 
INTEGER; EXTERN; 
BEGIN (* #4444444: DECLARATIONS COMPLETE 0 RA KK RK 
oO cK: MATIN PROGRAM BEGINS HERE 2c RRR RR >) 
(*Prompt for library name and 
module to insert*) 
WRITE('Library Name: '); READLN(Lib_Name) ; 
WRITE('Module Name: '); READLN(Module_Name) ; 
(*Initialize lib for update access*) 
status := LBR$INI_CONTROL (lib_index_ptr, 


IADDRESS (LBR$C_UPDATE) , (*Update access*) 
IADDRESS(LBR$C_TYP_TXT)); (*Text library*) 
IF NOT ODD(status) THEN («Check error status*) 
WRITELN('Initialization Failed') 
ELSE («Initialization was successful*) 
BEGIN 
status := LBR$OPEN (lib_index_ptr, (*Open the library) 
Lib_Name) ; 
IF NOT ODD(status) THEN (*Check error status*) 
WRITELN('Open Not Successful') 
ELSE (*Open was successful*) 
BEGIN (*Is module already in the library?*) 
status := LBR$LOOKUP_KEY (lib_index_ptr, 
Module_Name, 
txtrfa_ptr) ; 
IF ODD(status) THEN (*Check status. Should not be odd*) 
WRITELN('Lookup key was successful.', 
'The module is already in the library. ') 
ELSE (*Did lookup key fail because key not found?) 
IF status = IADDRESS(LBR$_KEYNOTFND) THEN © 
Key_Not_Found := TRUE 
END 
END; 


Example 8—2 Cont'd. on next page 
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Example 8—2 (Cont.) Inserting a Module Into a Library Using VAX Pascal 


(****xk4If LBRSLOOKUP_KEY failed because the key was not found 
(as expected), we can open the file containing the new module, 
and write the module's records to the library file*x******) 

IF Key_Not_Found THEN 


BEGIN 
OPEN (Textin,Module_Name,old) ; 
RESET (Textin) ; 
WHILE NOT EOF(Textin) DO (*Repeat until end of file*) 
BEGIN 4 ] 
READ (Textin,Text_Data_Record) ; (*Read record from 


external file*) 
status := LBR$PUT_RECORD (lib_index_ptr, (*Write*) 
Text_Data_Record, (*record to*) 
txtrfa_ptr) ; (*library*) 
IF NOT ODD(status) THEN 
WRITELN('Put Record Routine Not Successful') 
END; (*of WHILE statement*) 
IF ODD(status) THEN (*True if all the records have been 
successfully written into the library*) 
BEGIN 
status := LBR$PUT_END (lib_index_ptr); (*Write end of 
module record*) 
’ IF NOT ODD(status) THEN 
WRITELN('Put End Routine Not Successful') 
ELSE _ (*Insert key for new module*) 
BEGIN 
status := LBR$INSERT_KEY (lib_index_ptr, 
Module_Name, 
txtrfa_ptr) ; 
IF NOT ODD(status) THEN 
WRITELN('Insert Key Not Successful') 
END 
END 
END; 
status := LBR$CLOSE(lib_index_ptr) ; 
IF NOT ODD(status) THEN 
WRITELN('Close Not Successful') 
END. (*of program insertmod*) 


Each item in the following list corresponds to a number highlighted in 
Example 8-2. 


@ Call LBRSINI_CONTROL, specifying that the function to be performed is 
update and that the library type is text. 


® Call LBR$LOOKUP_KEY to see whether the module to be inserted is 
already in the library. 


© Call LBRSLOOKUP_KEY to see whether the lookup key failed because 
the key was not found. (In this case, the status value is 


LBR$_KEYNOTEND.) 


© Read a record from the input file, then use LBR$PUT_RECORD to write 
the record to the library. When all the records have been written to the 
library, use LBR6PUT_END to write an end of module record. 


@ Use LBR$INSERT_KEY to insert a key for the module into the current 
index. 
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Example 8-3 illustrates the use of LBR routines to extract a module from a 
library. 


Example 8-3 Extracting a Module from a Library Using VAX Pascal 





PROGRAM extractmod (INPUT , OUTPUT ,Textout) ; 
(«This program extracts a module from a library*) 


TYPE 
Rfa_Ptr = ARRAY [0..1] OF INTEGER; (*Data type of RFA of module*) 
VAR 
LBR$C_UPDATE, (*Constants for LBR$INI_CONTROL*) 
LBR$C_TYP_TXT, (*Defined in $LBRDEF macro*) 
RMS$_EOF : [EXTERNAL] INTEGER; (*RMS return status; defined in 


$RMSDEF macro*) 
Lib_Name : VARYING [128] OF CHAR; (x*Name of library receiving module*) 
Module_Name : VARYING [31] OF CHAR; (*Name of module to insert*) 


Extracted_File : VARYING [31] OF CHAR; (*Name of file to hold 
extracted module*) 

Outtext : PACKED ARRAY [1..255] OF CHAR; (*Extracted mod put here, *) 

Outtext2 : VARYING [255] OF CHAR; (* then moved to here*) 

i: INTEGER; (*For loop control*) 

Textout : FILE OF VARYING [255] OF CHAR; (*File containing extracted 
module*) 

nullstring : CHAR; (*nullstring, pos, and len used to*) 

pos, len : INTEGER; (*find string in extracted file recd*) 

lib_index_ptr : UNSIGNED; (*Value returned in library init*) 

status : UNSIGNED; (*Return status for function calls*) 

txtrfa_ptr : Rfa_Ptr; (*For key lookup and insertion*) 


(*-*-*-*-Function Definitions-*-*-*-*) 
(*Function that returns library 
control index used by librarian*) 
FUNCTION LBR$INI_CONTROL (VAR library_index: UNSIGNED; 
func: UNSIGNED; 
typ: UNSIGNED; 
VAR namblk: ARRAY[1..u: INTEGER] 
OF INTEGER := %IMMED 0): 
INTEGER; EXTERN; 
(*Function that creates/opens library*) 
FUNCTION LBR$OPEN (library_index: UNSIGNED; 
fns: [class_s]PACKED ARRAY[1..u: INTEGER] OF CHAR; 
create_options: ARRAY [12..u2: INTEGER] OF INTEGER := 
%IMMED 0; 
dns: [CLASS_S] PACKED ARRAY [13..u3: INTEGER] OF CHAR 
_:= YIMMED 0; 
rlfna: ARRAY [14..u4: INTEGER] OF INTEGER := %IMMED 0; 
rns: [CLASS_S] PACKED ARRAY [15..u5:INTEGER] OF CHAR := 
%IMMED 0; 
VAR rnslen: INTEGER := %IMMED 0): 
INTEGER; EXTERN; 
(*Function that finds a key in an index*) 
FUNCTION LBR$LOOKUP_KEY (library_index: UNSIGNED; 
key_name: [CLASS_S] PACKED ARRAY [1..u: INTEGER] OF 
CHAR ; 
VAR txtrfa: Rfa_Ptr): 
INTEGER; EXTERN; 





Example 8—3 Cont'd. on next page 
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Example 8—3 (Cont.) Extracting a Module from a Library Using VAX Pascal 


(*Function that retrieves records from modules*) 
FUNCTION LBR$GET_RECORD (library_index: UNSIGNED ; 
var textline: [CLASS_S] PACKED ARRAY [1..u: INTEGER] OF 
CHAR) : 
INTEGER ; 
EXTERN ; 
(*Function that closes library*) 
FUNCTION LBR$CLOSE (library_index: UNSIGNED) : 
INTEGER; EXTERN; 
BEGIN (+ see DECLARATIONS COMPLETE 2242-2 kok 2 2k ok 2 ok 2 a a Ka RK ok 
Fo ORE: MAIN PROGRAM BEGINS HERE +244: RRR RR *) 
(* Get Library Name, Module To Extract, And File To Hold Extracted Module *) 
WRITE('Library Name: '); READLN(Lib_Name) ; 
WRITE('Module Name: '); READLN(Module_Name) ; 
WRITE('Extract Into File: '); READLN(Extracted_File) ; 


status := LBR$INI_CONTROL (lib_index_ptr, 1) 
IADDRESS (LBR$C_UPDATE) , 
IADDRESS (LBR$C_TYP_TXT) ) ; 
IF NOT ODD(status) THEN 
WRITELN('Initialization Failed') 


ELSE 
BEGIN 
status := LBR$OPEN (lib_index_ptr, 
Lib_Name) ; 
IF NOT ODD(status) THEN 
WRITELN('Open Not Successful') 
ELSE 
BEGIN 2) 
status := LBR$LOOKUP_KEY (lib_index_ptr, 
Module_Name, 
txtrfa_ptr) ; 
IF NOT ODD(status) THEN 
WRITELN('Lookup Key Not Successful') 
ELSE 
BEGIN 3] 
OPEN (Textout ,Extracted_File, new) ; 
REWRITE (Textout) 
END 
END 
END; 
WHILE ODD(status) DO 
BEGIN 
nullstring := ''(0); 
FOR i := 1 TO 255 DO 14) 


Outtext [i] := nullstring; 
status := LBR$GET_RECORD (lib_index_ptr, 
Outtext) ; 
IF NOT ODD(status) THEN 
BEGIN 15 
IF status = IADDRESS(RMS$_EOF) THEN 
WRITELN(' RMS end of file') 
END 


Example 8—3 Cont'd. on next page 
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ELSE 
BEGIN 6 
pos := INDEX(Outtext, nullstring); (*find first null 
in Outtext*) 
len := pos - 1; (*length of Outtext to first null*) 
IF len >= 1 THEN 
BEGIN 
Outtext2 := SUBSTR(Outtext,1,LEN) ; 
WRITE (Textout , Quttext2) 
END 
END 
END; (*of WHILE*) 
status := LBR$CLOSE(1ib_index_ptr) ; 
IF NOT ODD(status) THEN 
WRITELN('Close Not Successful') 
END. (*of program extractmod*) 


Each item in the following list corresponds to a number highlighted in 
Example 8-3. 


@ Call LBR$INI_CONTROL, specifying that the function to be performed is 
update and that the library type is text. 


® Call LBR$LOOKUP_KEY to find the key that points to the module you 
want to extract. 


© Open an output file to receive the extracted module. 


© Initialize the variable that is to receive the extracted records to null 
characters. 


© Call LBR$GET_RECORD to see if there are more records in the file 
(module). A failure indicates that the end of the file has been reached. 


@ Write the extracted record data to the output file. This record should 
consist only of the data up to the first null character. 


Example 8-4 illustrates the use of LBR routines to delete a library. 
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Example 8—4 Deleting a Module from a Library Using VAX Pascal 





PROGRAM deletemod (INPUT, OUTPUT) ; 
(*This program deletes a module from a library*) 


TYPE 
Rfa_Ptr = ARRAY [0..1] OF INTEGER; (*Data type of RFA of module*) 
VAR 
LBR$C_UPDATE, («Constants for LBR$INI_CONTROL*) 
LBR$C_TYP_TXT, (*Defined in $LBRDEF macro*) 


LBR$_KEYNOTFND : [EXTERNAL] INTEGER; (*Error code for LBR$LOOKUP_KEY*) 
Lib_Name : VARYING [128] OF CHAR; (*Name of library receiving module*) 
Module_Name : VARYING [31] OF CHAR; (*Name of module to insert*) 
Text_Data_Record : VARYING [255] OF CHAR; (*Record in new module) 
Textin : FILE OF VARYING [255] OF CHAR; (*File containing new module*) 


lib_index_ptr : UNSIGNED; (*Value returned in library init*) 
status : UNSIGNED; (*Return status for function calls*) 
txtrfa_ptr : Rfa_Ptr; (*For key lookup and insertion*) 


Key_Not_Found : BOOLEAN := FALSE; (*True if new mod not already in lib*) 
(*-*-*-*-Function Definitions-*-*-*-*) 
(*Function that returns library 
control index used by librarian*) 
FUNCTION LBR$INI_CONTROL (VAR library_index: UNSIGNED; 
func: UNSIGNED; 
typ: UNSIGNED; 
VAR namblk: ARRAY[1..u: INTEGER] 
OF INTEGER := %IMMED 0): 
INTEGER; EXTERN; 
(*Function that creates/opens library*) 
FUNCTION LBR$OPEN (library_index: UNSIGNED; 
fns: [class_s]PACKED ARRAY[1..u:INTEGER] OF CHAR; 
create_options: ARRAY [12..u2: INTEGER] OF INTEGER := 
%IMMED 0; 
dns: [CLASS_S] PACKED ARRAY [13..u3:INTEGER] OF CHAR 
:= %IMMED 0; 
rlfna: ARRAY [14..u4: INTEGER] OF INTEGER := %IMMED 0; 
rns: [CLASS_S] PACKED ARRAY [15..u5:INTEGER] OF CHAR := 
%IMMED 0; 
VAR rnslen: INTEGER := %IMMED 0): 
INTEGER; EXTERN; — 
(*Function that finds a key in index*) 
FUNCTION LBR$LOOKUP_KEY (library_index: UNSIGNED; 
key_name: [CLASS_S] PACKED ARRAY [1..u: INTEGER] OF 
CHAR ; 
VAR txtrfa: Rfa_Ptr): 
INTEGER; EXTERN; 
(*Function that removes a key from an index*) 
FUNCTION LBR$DELETE_KEY (library_index: UNSIGNED; 
key_name: [CLASS_S] PACKED ARRAY [1..u: INTEGER] OF 
CHAR) : 
INTEGER ; 
EXTERN ; 


Example 8—4 Cont’d. on next page 
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8.2 Examples of Using the LBR Routines 


Example 8—4 (Cont.) Deleting a Module from a Library Using VAX Pascal 





(*Function that deletes all the records 
associated with a module*) 
FUNCTION LBR$DELETE_DATA (library_index: UNSIGNED; 
txtrfa: Rfa_Ptr): 
INTEGER; 
EXTERN ; 
(*Function that closes library*) 
FUNCTION LBR$CLOSE (library_index: UNSIGNED): 
INTEGER; EXTERN; 


BEGIN (+ REE DECLARATIONS COMPLETE 222k 22k 22 kok 2k ok 2k i ok 2k kK 2k ook ak kk 
AE: MATIN PROGRAM BEGINS HERE 2k RR RRR ok) 
(* Get Library Name and Module to Delete *) 
WRITE('Library Name: '); READLN(Lib_Name) ; 
WRITE('Module Name: '); READLN(Module_Name) ; 
(«Initialize lib for update access*) 
status := LBR$INI_CONTROL (lib_index_ptr, 
IADDRESS (LBR$C_UPDATE) , (*Update access*) 
IADDRESS(LBR$C_TYP_TXT)); (*Text library*) 
IF NOT ODD(status) THEN (*Check error status*) 
WRITELN(' Initialization Failed') : 
ELSE (*Initialization was successful*) 
BEGIN 
status := LBR$OPEN (lib_index_ptr, (*Open the library*) 
Lib_Name) ; 
IF NOT ODD(status) THEN (*Check error status*) 
WRITELN('Open Not Successful') 
ELSE (*Open was successful*) 
BEGIN @ (Is module in the library?*) 
status := LBR$LOOKUP_KEY (lib_index_ptr, 
Module_Name, 
txtrfa_ptr) ; 
IF NOT ODD(status) THEN (*Check status*) 
WRITELN('Lookup Key Not Successful') 
END 
END; 
IF ODD(status) THEN (*Key was found; delete it*) 
BEGIN 
status := LBR$DELETE_KEY  § (lib_index_ptr, © 
Module_Name) ; 
IF NOT ODD(status) THEN 
WRITELN('Delete Key Routine Not Successful') 
_ ELSE (*Delete key was successful*) 
BEGIN (*Now delete module's data records*) 
status := LBR$DELETE_DATA (lib_index_ptr, 
txtrfa_ptr) ; 
IF NOT ODD(status) THEN 
WRITELN('Delete Data Routine Not Successful') 
END 
END; 
status := LBR$CLOSE(lib_index_ptr); (*Close the library*) 
IF NOT ODD(status) THEN 
WRITELN('Close Not Successful') ; 
END. (*of program deletemod*) 
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8.2 Examples of Using the LBR Routines 


Each item in the following list corresponds to a number highlighted in 
Example 8-4. 


@ Call LBR$INI_CONTROL, specifying that the function to be performed is 
update and the library type is text. 


@ Call LBR$LOOKUP_KEY to find the key associated with the module you 
want to delete. 


© Call LBR$DELETE_KEY to delete the key associated with the module 
you want to delete. If more than one key points to the module, you need 
to call LBR$LOOKUP_KEY and LBR$DELETE_KEY for each key. 


© Call LBRS${DELETE_DATA to delete the module (the module header and 
data) from the library. 





8.3 LBR Routines 


The following pages describe the individual LBR routines. 
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LBRSCLOSE 


LBRSCLOSE Close a Library 


The LBR$CLOSE routine closes an open library. 








FORMAT LBR$CLOSE _library_index 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENT library_index 
VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 





DESCRIPTION — When you are finished working with a library, you should call LBR$CLOSE 
to close it. Upon successful completion, LBR$CLOSE closes the open library 
and deallocates all of the memory used for processing it. 





CONDITION a | | 
VALUES LBR$_ILLCTL Specified library control index not valid. 
RETURNED LBR$_LIBNOTOPN Specified library not open. 
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LBR$DELETE_DATA Delete a Module’s Data 


The LBR$DELETE_DATA routine deletes the module header and data 
associated with the specified module. 





FORMAT 


LBR$DELETE_DATA _library_index ,txtrfa 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


library_index 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 


txtrfa 


VMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: read only 

mechanism: by reference 


Record’s file address (RFA) of the module header for the module you want 
to delete. The txtrfa argument is the address of the 2-longword array that 
contains the RFA. You can obtain the RFA of a module header by calling 
LBR$LOOKUP_exit KEY or LBR6PUT_RECORD. 





DESCRIPTION 


If you want to delete a library. module, you must first call LBR$DELETE_KEY 
to delete any keys that point to it. If no library index keys are pointing at 
the module header, LBR$}DELETE_DATA deletes the module header and 
associated data records; otherwise, this routine returns the error 
LBR$_STILLKEYS. 


Note that other librarian routines may reuse data blocks that contain no data. 
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LBRSDELETE_DATA 





CONDITION LBR$_ILLCTL Specified lib | ind lid 
aa t t : 
VALUES LBR$_INVRFA oa oe os a eo 
= t : 
RETURNED pecme not vali 
LBR$_LIBNOTOPN Specified library not open. 
LBR$_STILLKEYS Keys in other indexes still point at the module 
header. Therefore, the specified module was not 
deleted. 
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LBR$DELETE_KEY Delete a Key 


The LBR$DELETE_KEY routine deletes a key from a library index. 











FORMAT LBR$SDELETE_KEY /ibrary_index ,key_name 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value . 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS __ /ibrary_index 


VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of a longword containing the index. 


key_name 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Key to be deleted from the library index. For libraries with binary keys, the 
key_name argument is the address of an unsigned longword containing the 
key number. 


For libraries with ASCII keys, the keyname argument is the address 
of the string descriptor pointing to the key with the following argument 
characteristics. 


Argument 

Characteristics Entry 

VMS Usage Char_string 
Type Character string 
Access Read only 
Mechanism By descriptor 
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LBR$DELETE_KEY 





DESCRIPTION __ If LBR$DELETE_KEY finds the key specified by key_name in the current 
index, it deletes the key. Note that, if you want to delete a library module, 
you should first use LBRS$DELETE_KEY to delete any keys that point to it, 
then use LBR$DELETE_DATA to delete the module’s header and associated 
data. 


You cannot call LBR$DELETE_KEY from within the user-supplied routine 
specified in LBRS5SEARCH or LBR$GET_INDEX. 





CONDITION a | | 
VALUES LBR$_ILLCTL species library control index not valid. 
RETURNED LBR$_KEYNOTFND Specified key not found. 

LBR$_LIBNOTOPN Specified library not open. 

LBR$_UPDURTRAV Specified index update not valid in a user-supplied 


routine specified in LBRSSEARCH or 
LBRSGET_INDEX. 
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LBR$FIND Look Up a Module by Its RFA 


The LBR$SFIND routine sets the current internal read context for the library 
to the library module specified. 





FORMAT 


LBRS$FIND _library_index ,txtrfa 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


library_index 


VMS usage: longword_unsigned 


type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 


txtrfa 


VMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: read only 

mechanism: by reference 


RFA (record’s file address) of the module header for the module you 
want to access. The txtrfa argument is the address of a 2-longword array 
containing the RFA. You can obtain the RFA of a module header by calling 
LBR$LOOKUP_KEY or LBR$PUT_RECORD. 





DESCRIPTION 


You use the LBR$FIND routine to access a module that you had accessed 
earlier in your program. For example, if you look up several keys with 
LBR$LOOKUP_KEY, you can save the RFAs returned by LBR6LOOKUP_KEY 
and later use LBR$FIND to reaccess the modules. Thus, you do not have to 
look up the module header’s key every time you want to access the module. 
If the specified RFA is valid, LBR$FIND initializes internal tables so that you 
can read the associated data. 
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LBRSFIND 

CONDITION aidan deste Age. ied 3 

VALUES pater ile : se — index not valid. 

RETURNED = pecifie not valid. 
LBR$_LIBNOTOPN Specified library not open. 
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LBRSFLUSH 


LBR$FLUSH Recover Virtual Memory 


The LBR$FLUSH routine writes modified blocks back to the library file and 
frees the virtual memory the blocks had been using. 





FORMAT 


LBRSFLUSH /ibrary_index ,block_type 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


library_index 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 


block_type 


VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by value 


Extent of the flush operation. The block_type argument contains the 
longword value that indicates how the flush operation proceeds. If you 
specify LBR$C_FLUSHDATA, the data blocks are flushed. If you specify 
LBR$C_FLUSHALL, first the data blocks and then the current library index 
are flushed. 


The LBR$ symbols LBR$C_FLUSHDATA and LBR$C_FLUSHALL are defined 
in the macro $LBRDEF (found in SYS$LIBRARY:STARLET.MLB), which must 
be assembled and then linked with your program. 





DESCRIPTION 


LBR$FLUSH cannot be called from other librarian routines that reference 
cache addresses or by routines called by librarian routines. 
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LBRS$FLUSH 

CONDITION ? | 

VALUES LBR$_NORMAL Operation completed successfully. 
RETURNED LBR$_BADPARAM Error. A value passed to the LBR$FLUSH routine 


was either out of range or an illegal value. 


LBR$_WRITERR Error. An error occurred during the writing of the 
cached update blocks to the library file. 
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LBR$GET_HEADER 


LBRS$GET_HEADER 1 Retrieve Library Header 


Information 


The LBR$GET_HEADER routine returns information from the library's 
header to the caller. 











FORMAT LBR$GET_HEADER /ibrary_index ,retary 

RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 

ARGUMENTS library_index 


VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 


retary 

VMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: write only 


mechanism: by reference 


Array of 128 longwords that receives the library header. The retary argument 
is the address of the array that contains the header information. The 
information returned in the array is listed in the following table (the symbols 
are defined by the $LHIDEF macro in SYS$LIBRARY:STARLET.MLB). 


Offset in 
Longwords Symbolic Name Contents 
O LHISL__TYPE Library type (see LBRSOPEN for possible 
values) 
LHI$L __NINDEX Number of indexes 
2 LHI$L _MAJORID Library format major identification 
3 LHIS$L__MINORID Library format minor identification 
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LBRSGET_HEADER 


Offset in 
Longwords 


4 
12 
14 
16 
17 
18 
19 


21 


32-128 


Symbolic Name 


LHIST_LBRVER 
LHISL_CREDAT 
LHISL_UPDTIM 
LHIS$L__UPDHIS 
LHISL__FREEVBN 
LHISL__FREEBLK 
LHISB_NEXTRFA 


LHISL_NEXTVBN 
LHI$L__FREIDXBLK 
LHISL __FREEIDX 
LHISL __HIPREAL 
LHI$L__IDXBLKS 
LHI$L_IDXCNT 
LHISL_MODCNT 


LHISL__MHDUSZ 
LHI$L__MAXLUHREC 
LHI$SL__NUMLUHREC 


LHI$L_LIBSTATUS 


Contents 


ASCIC version of Librarian 
Creation date/time 

Date/time of last update 

VBN of start of update history 
First logically deleted block 
Number of deleted blocks 


Record’s File Address (RFA) of end of 
library 


Next VBN to allocate at end of file 
Number of free preallocated index blocks 
Listhead for preallocated index blocks 
VBN of highest preallocated block 
Number of index blocks in use 

Number of index entries (total) 


Number of entries in index 1 (module 
names) 


Number of bytes of additional information 
reserved in module header 


Maximum number of library update 
history records maintained 


Number of library update history records 
in history 

Library status (false if there was an error 
closing the library) 


Reserved by DIGITAL 








DESCRIPTION — On successful completion, LBR$GET_HEADER places the library header 
information into the array of 128 longwords. 
Note that the offset is the byte offset of the value into the header structure. 
You can convert the offset to a longword subscript by dividing the offset by 4 
and adding 1 (assuming that subscripts in your programming language begin 
with 1). 

eapereiead LBR$_LIBNOTOPN Specified lib t 

hl alata at LBR$_ILLCTL eave ie : ee t valid 

RETURNED 2 pecified library control index not valid. 
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LBR$SGET_HELP 


LBR$SGET_HELP Retrieve Help Text 


The LBR$GET_HELP routine retrieves help text from a help library, 
displaying it on SYS$OUTPUT or calling your routine for each record 








returned. 
FORMAT LBRS$GET_HELP /ibrary_index [, line_width] [, routine] 
[,data] [,key_1][,key_2 ... ,key_10] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS library_index 
VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 


line_width 


VMS usage: longword_signed 
type: longword (signed) 
access: read only 
mechanism: by reference 


Width of the help text line. The line_width argument is the address of a 
longword containing the width of the listing line. If you do not supply a line 
width or if you specify 0, the line width defaults to 80 characters per line. 


routine 

VMS usage: procedure 

type: procedure entry mask 
access: read only 


mechanism: by reference 


Routine called for each line of text you want output. The routine argument is 
the address of the entry mask for this user-written routine. 


If you do not supply a routine argument, LBR6GET_HELP calls the Run- 
Time Library procedure LIB5;,PUT_OUTPUT to send the help text lines to the 
current output device (SYSSOUTPUT). However, if you want SYS$SOUTPUT 
for your program to be a disk file rather than the terminal, you should supply 
a routine to output the text. 
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LBRSGET_HELP 
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The routine you specify is called with an argument list of four longwords: 
1. The first argument is the address of a string descriptor for the output line. 


2 The second argument is the address of an unsigned longword containing 
flag bits that describe the contents of the text being passed. The possible 
flags are as follows: 

HLP$M_NOHLPTXT Specified help text cannot be found. 
HLP$M_KEYNAMLIN — Text contains key names of the printed text. 


HLP$M_OTHERINFO Text is part of the information provided on additional 
help available. 


(The $HLPDEF macro in SYS$LIBRARY:STARLET.MLB defines these flag 
symbols.) 


Note that, if no flag bit is set, help text is passed. 


3 The third argument is the address stipulated in the data argument 
specified in the call to LBR$GET_HELP (or the address of a 0 constant if 
the data argument is zero or was omitted). 


4 The fourth argument is a longword containing the current key level. 


The routine you specify must return with success or failure status. A failure 
status (low bit = 0) terminates the current call to LBR$GET_HELP. 


data 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 


mechanism: by reference 


Data passed to the routine specified in the routine argument. The data 
argument is the address of data for the routine. The address is passed to 
the routine specified in the routine argument. If you omit this argument 
or specify it as zero, then the argument passed in your routine will be the 
address of a zero constant. 


key_1,key_2, ...,key_10 
VMS usage: longword_signed 
type: longword (signed) 
access: read only 

mechanism: by descriptor 


Level of the help text to be output. Each key_1,key_2, ... ,key_10 
argument is the address of a descriptor pointing to the key for that level. 


If the key_1 descriptor is 0 or if it is not present, LBR6GET_HELP assumes 
that the key_1 name is HELP, and it ignores all the other keys. For key_2 
through key_10, a descriptor address of 0, or a length of 0, or a string address 
of 0 terminates the list. 


Librarian (LBR) Routines 
LBR$GET_HELP 


The key argument may contain any of the following special character strings: 


String Meaning 
* Return all level 1 help text in the library. 
KEY cs Return all help text associated with the specified key and its subkeys 


(valid for level 1 keys only). 
abe Return all help text in the library. 





DESCRIPTION LBR$GET_HELP returns all help text in the same format as the output 
returned by the DCL command HELP; that is, it indents two spaces for every 
key level of text displayed. (Because of this formatting, you may want to 
make your help messages shorter than 80 characters, so they fit on one line 
on terminal screens with the width set to 80.) If you do not want the help 
text indented to the appropriate help level, you must supply your own routine 
to change the format. 


Note that most application programs use LBRSOUTPUT_HELP instead of 
LBR$GET_HELP. 





CONDITION aa | | 
VALUES LBR$_ILLCTL Specified library control index not valid. 
RETURNED LBRS_LIBNOTOPN Specified library not open. 


LBR$_NOTHLPLIB Specified library not a help library. 
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LBRSGET_HISTORY Retrieve a Library Update 


History Record 


The LBR$GET_HISTORY routine returns each library update history record 
to a user-specified action routine. 





FORMAT 


LBR$GET_HISTORY _library_index ,action_routine 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


library_index 


VMS usage: longword_unsigned 


- type: longword (unsigned) 


access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The 
library—index argument is the address of the longword that contains the 
index. 


action_routine 


VMS usage: procedure 

type: procedure entry mask 
access: modify 

mechanism: by reference 


User-supplied routine for processing library update history records. The 
action_routine argument is the address of the entry mask of this user- 
supplied routine. The routine is invoked once for each update history record 
in the library. One argument is passed to the routine, namely, the address of 
a descriptor pointing to a history record. 





DESCRIPTION 
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This routine retrieves the library update history records written by the routine 
LBR$PUT_HISTORY. 
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LBRS$GET_HISTORY 





CONDITION LBR$_NORMAL N | exit f h i 
I t t tine. 
VALUES LBR$_EMPTYHIST oe a ee ne ional cod 
il istory empty. is is an informational code, not 
RETURNED an error code. 
LBR$_NOHISTORY No update history. This is an informational code, 


not an error code. 
LBR$_INTRNLERR Internal librarian routine error occurred. 
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LBRSGET_INDEX 


LBRS$GET_INDEX Call a Routine for Selected 


Index Keys 


The LBR$GET_INDEX routine calls a user-supplied routine for selected 
keys in an index. 





FORMAT 


LBR$GET_INDEX | library_index ,index_number 
,routine_name [,match_desc] 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 
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library_index 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 


index_number 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Number of the library index. The index_number argument is the address 
of a longword containing the index number. This is the index number 
associated with the keys you want to use as input to the user-supplied routine 
(see Section 8.1.2.3). 


routine_name 

VMS usage: procedure 

type: procedure entry mask 
access: read only 

mechanism: by reference 


User-supplied routine called for each of the specified index keys. The 
routine_name argument is the address of the entry mask for this user- 
supplied routine. 


Librarian (LBR) Routines 
LBR$GET_INDEX 


LBR$GET_INDEX passes two arguments to the routine: 
e A key name. 


- For libraries with ASCII keys, the key_name argument is the address 
of a string descriptor pointing to the key. Note that the string and the 
string descriptor passed to the routine are valid only for the duration 
of that call. The string must be privately copied if you need it again 
for more processing. 


- For libraries with binary keys, the key_name argument is the address 
of an unsigned longword containing the key number. 


e The record’s file address (RFA) of the module’s header for this key name. 
The RFA argument is the address of a 2-longword array that contains the 
RFA. 


The routine must return a value to indicate success or failure. If the routine 
returns a false value (low bit = 0), LBR$GET_INDEX stops searching the 
index and returns the status value of the user-specified routine to the calling 
program. 


The routine cannot contain calls to either LBR$DELETE—_KEY or 
LBR$INSERT_KEY. 


match_desc 


VMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Key matching identifier. The match—_desc argument is the address of a string 
descriptor pointing to a string used to identify which keys result in calls to 
the user-supplied routine. Wildcard characters are allowed in this string. If 
you omit this argument, the routine is called for every key in the index. The 
match_desc argument is valid only for libraries that have ASCII keys. 





DESCRIPTION 


LBR$GET_INDEX searches through the specified index for a key that matches 
the argument match_desc. Each time it finds a match, it calls the routine 
specified by the routine_name argument. If you do not specify the match_ 
desc argument, it calls the routine for every key in the index. 


For example, if you call LBR$GET_INDEX with match_desc equal to TR* 
and index_number set to 1 (module name table), then LBR$GET_INDEX 
calls routine_name for each module whose name begins with TR. 





CONDITION 
VALUES 
RETURNED 


LBR$_ILLCTL Specified library control index not valid. 
LBR$_ILLIDXNUM Specified index number not valid. 
LBR$_LIBNOTOPN Specified library not open. 
LBR$_NULIDX Specified library empty. 
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LBRS$GET_RECORD Read a Data Record 


The LBR$GET_RECORD routine returns the next data record in the module 
associated with a specified key. — 











FORMAT LBR$GET_RECORD _library_index [, inbufdes] 
[,outbufdes] 

RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 

ARGUMENTS library_index 


LBR-38 


VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The 
library—index argument is the address of the longword that contains the 
index. The library must be open and LBR$LOOKUP_KEY or LBR$FIND must 
have been called to find the key associated with the module whose records 
you want to read. 


inbufdes 


VMS usage: char_string 
type: character string 
access: write only 
mechanism: by descriptor 


User buffer to receive the record. The inbufdes argument is the address 

of a string descriptor that points to the buffer that receives the record from 
LBR$GET_RECORD. This argument is required when the librarian subroutine 
record access is set to move mode (which is the default). This argument is 
not used if the record access mode is set to locate mode. The DESCRIPTION 
section contains more information about the locate and move modes. 
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outbufdes 

VMS usage: char_string 
type: character string 
access: write only 


mechanism: by descriptor 


String descriptor that receives the actual length and address of the data for 
the record returned. The outbufdes argument is the address of the string 
descriptor for the returned record. The length and address fields of the string 
descriptor are filled in by the LBR6GET_RECORD routine. This parameter 
must be specified when Librarian subroutine record access is set to locate 
mode. This parameter is optional if record access mode is set to move mode. 
The DESCRIPTION section contains more information about the locate and 
move modes. 





DESCRIPTION 


Before calling LBR$GET_RECORD, you must first call LBR6LOOKUP_KEY or 
LBRS$FIND to set the internal library read context to the record's file address 
(RFA) of the module header of the module whose records you want to read. 


LBR$GET_RECORD uses two record access modes: locate mode and move 
mode. Move mode is the default. The LBR$6SET_LOCATE and LBR$SET_ 
MOVE subroutines set these modes. The record access modes are mutually 
exclusive; that is, when one is set the other is turned off. If move mode 

is set, LBR6GET_RECORD copies the record to the user-specified buffer 
described by inbufdes. If you have optionally specified the output buffer 
string descriptor, outbufdes, the librarian fills it with the actual length and 
address of the data. If locate mode is set, LBR6GET_RECORD returns the 
record by way of an internal subroutine buffer, pointing the outbufdes 
descriptor to the internal buffer. The second parameter, inbufdes, is not used 
when locate mode is set. 





CONDITION 
VALUES 
RETURNED 


LBR$_ILLCTL Specified library control index not valid. 
LBR$_LIBNOTOPN Specified library not open. 

LBR$_LKPNOTDON Requested key lookup not done. 

RMS$_EOF Error. An attempt has been made to read past the 


logical end of the data in the module. 
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LBRSINI_CONTROL Initialize a Library Control 
Structure 


The LBR$SINI_CONTROL routine initializes a control structure, called a 
library control index, to identify the library for use by other Librarian 








routines. 
FORMAT LBRSINI_CONTROL /ibrary_index ,func [, type] 
[,namblk] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS __ /ibrary_index 


VMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


Library control index returned by the LBR$INI_-CONTROL routine. The 
library_index argument is the address of a longword that is to receive the 


index. 

func 

VMS usage: function_code 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Library function to be performed. The func argument is the address of the 
longword that contains the library function. Valid functions are 
LBR$C_CREATE, LBR$C_READ, and LBR$C_UPDATE. (These symbols are 
defined by the $LBRDEF macro in SYS$LIBRARY:STARLET.MLB.) 
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type 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Library type. The type argument is the address of the longword containing 
the library type. Valid library types are LBR$C_TYP_OB] (object or shareable 
image), LBR6C_TYP_MLB (macro), LBR$C_TYP_HLP (help), LBR$C_TYP_ 
TXT (text), LBR6C_TYP_UNK (unknown), or, for user-developed libraries, a 
type in the range of LBR$C_TYP_USRLW through LBR$C_TYP_USRHI. 


namblk 

VMS usage: nam 

type: longword (unsigned) 
access: read only 


mechanism: by reference 


VMS RMS name block (NAM). The namblk argument is the address 

of a variable-length data structure containing an RMS NAM block. The 
LBR$OPEN routine fills in the information in the NAM block so that it can 
be used later to open the library. If the NAM block has this file identification 
in it from previous use, the LBR$60PEN routine uses the VMS RMS open- 
by-NAM block option. This argument is optional and should be used if 

the library will be opened many times during a single run of the program. 
For a detailed description of VMS RMS NAM blocks, see the VMS Record 
Management Services Manual. 





DESCRIPTION 


Except for the LBR6OUTPUT_HELP routine, you must call 
LBR$INI_-CONTROL before calling any other librarian routine. After you 
initialize the library control index, you must open the library or create a new 
one using the LBR$OPEN routine. You can then call other librarian routines 
that you need. After you finish working with a library, close it with the 
LBR$CLOSE routine. 


LBR$INI_CONTROL initializes a library by filling the longword referenced 
by the library_index argument with the control index of the library. Upon 
completion of the call, the index can be used to refer to the current library in 
all future routine calls. Therefore, your program must not alter this value. 


You can have up to 16 libraries open simultaneously in your program. 





CONDITION 
VALUES 
RETURNED 


LBR$_NORMAL Library control index initialized successfully. 
LBR$S_ILLFUNC Requested function not valid. 

LBR$_ILLTYP Specified library type not valid. 

LBR$_TOOMNYLIB Error. An attempt was made to allocate more than 


16 control indexes. 
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LBR$SINSERT_KEY Insert a New Key 


The LBRSINSERT_KEY routine inserts a new key in the current library 








index. 
FORMAT LBRSINSERT_KEY _ /ibrary_index ,key_name ,txtrfa 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS library_index 
VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_-CONTROL routine. The 
- library_index argument is the address of the longword that contains the 
index. 


key_name 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


Name of the new key you are inserting. 


If the library uses binary keys, the key_name argument is the address of an 
unsigned longword containing the value of the key. 


If the library uses ASCII keys, the key_name argument is the address of a 
string descriptor of the key with the following argument characteristics. 


Argument 

Characteristics Entry 

VMS Usage Char_string 
Type Character string 
Access Write only 
Mechanism By descriptor 
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txtrfa 

VMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: modify 


mechanism: by reference 


Record file address (RFA) of the module associated with the new key you 
are inserting. The txtrfa argument is the address of a 2-longword array 
containing the RFA. You can use the RFA returned by the first call to 
LBR$PUT_RECORD. 








DESCRIPTION You cannot call LBR$INSERT_KEY within the user-supplied routine specified 
in LBR$SEARCH or LBR$GET_INDEX. 
~ONornON LBR$_ILLCTL Specified lib | ind lid 
_ t t : 
VALUES LBR$_INVRFA is ae! ieee is ‘ ied d 
2 t tt ta. 
RETURN ED pecine oes not point to vail ata 
LBR$_DUPKEY index already contains the specified key. 
LBR$_LIBNOTOPN Specified library not open. 
LBR$_UPDURTRAV LBRSINSERT_KEY was called by the user-defined 


routine specified in LBRSSEARCH or 
LBRSGET_INDEX. 
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LBR$LOOKUP_KEY Look Up a Library Key 











The LBR$LOOKUP_KEY routine looks up a key in the library’s current index 


and prepares to access the data in the module associated with the key. 


FORMAT LBRSLOOKUP_KEY _/ibrary_index ,key_name ,txtrfa 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS __ l/library_index 
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VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 


key_name 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Name of the library key. If the library uses binary keys, the key_name 
argument is the address of the unsigned longword value of the key. 


If the library uses ASCII keys, the key_name argument is the address of a 
string descriptor for the key with the following argument characteristics. 


Argument Characteristics Entry 

VMS Usage Char_string 
Type Character string 
Access Read only 
Mechanism By descriptor 
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txtrfa 

VMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: write only 


mechanism: by reference 


The record’s file address (RFA) of the library module header. The txtrfa 
argument is the address of the 2-longword array that receives the RFA of the 
module header. 





DESCRIPTION 


If LBRS6LOOKUP_KEY finds the specified key, it initializes internal tables so 
that you can access the associated data. 


This routine returns the RFA (consisting of the virtual block number (VBN) 
and the byte offset) to the 2-longword array referenced by txtrfa. Note that 
the RFA is only 6 bytes long. 





CONDITION 
VALUES 
RETURNED 


LBR$_ILLCTL Specified library control index not valid. 
LBR$_INVRFA RFA obtained not valid. 
LBR$_KEYNOTFND Specified key not found. 
LBR$_LIBNOTOPN Specified library not open. 
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LBRSOPEN 


Open or Create a Library 


The LBR$OPEN routine opens an existing library or creates a new one. | 





FORMAT 


LBR$OPEN _/ibrary_index [,fns] [, create_options] [,dns] 
[rlfna] [rns] [,rnslen] 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 
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library_index 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of a longword containing the index. 


fns 

VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor 


File specification of the library. The fns argument is the address of:a string 
descriptor pointing to the file specification. Unless the VMS RMS NAM block 
address was previously supplied in the LBR$INI_-CONTROL routine and 
contained a file specification, this argument must be included. Otherwise, the 
librarian returns an error (LBR$_NOFILNAM). 


create_options 

VMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: read only 

mechanism: by reference 


Library characteristics. The create_options argument is the address of 

an array of 20 longwords that define the characteristics of the library 

you are creating. If you are creating a library with LBR$6C_CREATE, you 
must include the create-options argument. The following table shows the 
entries that the array must contain (the $LBRDEF and $CREDEF macros in 
SYS$LIBRARY:STARLET.MLB define the symbols listed). 


Offset in 
Longwords 


0 


9-20 
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Symbolic Name 


CRE$L_TYPE 
LBRSC_TYP_UNK (0) 
LBRSC_TYP_OBJ (1) 
LBR$C_TYP_MLB (2) 
LBRSC_TYP_HLP (3) 
LBRSC_TYP_TXT (4) 
(5-127) 

LBR$C_TYP_USR (128-255) 
CRESL_KEYLEN 


CRE$L_ALLOC 
CRE$L_IDXMAX 
CRE$L_UHDMAX 
CRE$L_ENTALL 
CRE$L__LUHMAX 
CRE$L_VERTYP 
CRE$C_VMSV2 
CRE$C_VMSV3 


CRE$L_IDXOPT 
CRE$C_HLPCASING 


CRE$C_OBJCASING 


CRE$C_MACTXTCAS 


LBRSOPEN 
Contents 
Library type: 
Unknown/unspecified 


Object and/or shareable image 
Macro 

Help 

Text 

Reserved by DIGITAL 
User-defined 


_ Maximum length of ASCII 


keys or, if 0, indicates 32-bit 
unsigned keys (binary keys) 


Initial library file allocation 


Number of library indexes 
(maximum of 8) 


Number of additional bytes to 
reserve in module header 


Numb of index entries to 
preallocate 


Maximum number of library 
update history records to 
maintain 


Format of library to create: 
VMS Version 2.0 

VMS Version 3.0 

Index key casing option: 


Treat character case as it is for 
help libraries 


Treat character case as it is for 
object libraries 


Treat character case as it is for 
macro and text libraries 


Reserved by DIGITAL 


The input of uppercase and lowercase characters is treated differently for 
help, object, macro, and text libraries. For details, see the VMS Librarian 
Utility Manual. 


dns 
VMS usage: 


type: 
access: 
mechanism: 


char_string 
character string 
read only 

by descriptor 


Default file specification. The dns argument is the address of the string 
descriptor that points to the default file specification. See the VMS Record 
Management Services Manual for details about how defaults are processed. 
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LBRSOPEN 
rlfna 
VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
Related file name. The rlfna argument is the address of a VMS RMS NAM 
block pointing to the related file name. If you do not specify rlfna, no related 
file name processing occurs. If a related file name is specified, only the file 
name, type, and version fields of the NAM block are used for related name 
block processing. The device and directory fields are not used. See the VMS 
Record Management Services Manual for details on processing related file 
names. 
rns 
VMS usage: char_string 
type: character string 
access: write only 
mechanism: by descriptor . 
Resultant file specification returned. The rns argument is the address of 
a string descriptor pointing to a buffer that is to receive the resultant file 
specification string. If an error occurs during an attempt to open the library, 
the expanded name string is returned instead. 
rnslen 
VMS usage: longword_signed 
type: longword (signed) 
access: write only 
mechanism: by reference 
Length of the resultant or expanded file name. The rnslen argument is the 
address of a longword receiving the length of the resultant file specification 
string (or the length of the expanded name string if there was an error in 
opening the library). 

DESCRIPTION You can call this routine only after you call LBR$INI_CONTROL and before 
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you call any other librarian routine except LBR5OUTPUT_HELP. 


When the library is successfully opened, the librarian routine reads the library 
header into memory and sets the default index to 1. 


If the library cannot be opened because it is already open for a write 
operation, LBR$OPEN retries the open operation every second for a 
maximum of 30 seconds before returning the VMS RMS error, RMS$_FLK, to 
the caller. 
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CONDITION 
VALUES 
RETURNED 


LBR$_OLDLIBRARY | 


LBR$_ERRCLOSE 


LBR$_ILLCREOPT 
LBR$_ILLCTL 
LBR$_ILLFMT 
LBR$_ILLFUNC 
LBRS_LIBOPN 
LBR$S_NOFILNAM 


LBR$_OLDMISMCH 


LBR$_TYPMISMCH 


Success. The specified library has been opened; 
the library was created with an old library format. 


Error. When the library was last modified while 
opened for write access, the write operation was 
interrupted. This left the library in an inconsistent 
state. 


Requested create options not valid or not supplied. 
Specified library control index not valid. 

Specified library format not valid. 

Specified library function not valid. 

Specified library already open. 


Error. The fns argument was not supplied or the 
VAX RMS NAM block was not filled in. 


Requested library function conflicts with old library 
type specified. 


Library type does not match the requested type. 
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LBRSOUTPUT_HELP Output Help Messages 


The LBRSOUTPUT_HELP routine outputs help text to a user-supplied 
output routine. The text is obtained from an explicitly named help library 
or, optionally, from user-specified default help libraries. An optional 
prompting mode is available that enables LBRS5OUTPUT_HELP to interact 
with you and continue to provide help information after the initial help 
request has been satisfied. 











FORMAT LBRSOUTPUT_HELP output_routine [,output_width] 
[,line_desc] [,library_name] 
[flags] [,input_routine] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS _— output_routine 
VMS usage: procedure 
type: procedure entry mask 
access: write only 
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mechanism: by reference 


Name of a routine that writes help text a line at a time. The output_routine 
argument is the address of the entry mask of the routine to call. You should 
specify either the address of LIB4,PUT_OUTPUT or a routine of your own 
that has the same calling format as LIB$PUT_OUTPUT. 


output_width 


VMS usage: longword_signed 
type: longword (signed) 
access: read only 
mechanism: by reference 


Width of the help-text line to be passed to the user-supplied output routine. 
The output—_width argument is the address of a longword containing the 
width of the text line to be passed to the user-supplied output routine. If 
you omit output—width or specify it as 0, the default output width is 80 
characters per line. 


line_desc 


VMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 
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Contents of the help request line. The line_desc argument is the address 
of a string descriptor pointing to a character string containing one or more 
help keys defining the help requested, for example, the HELP command line 
minus the HELP command and HELP command qualifiers. The default is a 
string descriptor for an empty string. 


library_name 


VMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Name of the main library. The library_name argument is the address of 

a string descriptor pointing to the main library file specification string. The 
default is a null string, which means you should use the default help libraries. 
If you omit the device and directory specifications, the default is SYS$HELP. 
The default file type is HLB. 


flags 

VMS usage: mask_ltongword 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Flags specifying help output options. The flags argument is the address of an 
unsigned longword that contains the following flags. 


Flag Description 


HLP$M_PROMPT When set, interactive help prompting is in effect. 


HLP$M_PROCESS When set, the process logical name table is searched for 
default help libraries. 


HLP$M_GROUP When set, the group logical name table is searched for 
group default help libraries. 


HLP$M_SYSTEM When set, the system logical name table is searched for 
system default help libraries. 


HLP$M_LIBLIST When set, the list of default libraries available is output 
with the list of topics available. 
HLP$M_HELP When set, the list of topics available in a help library is 


preceded by the major portion of the text on HELP. 


(The $HLPDEF macro in SYS$LIBRARY:STARLET.MLB defines these flag 
symbols.) 


If you omit this longword, the default is for prompting and all default library 
searching to be enabled, but no library list will be generated and no help text 
will precede the list of topics. 


input_routine 

VMS usage: procedure 

type: procedure entry mask 
access: read only 


mechanism: by reference 


Routine used for prompting. The input—routine argument is the address 
of the entry mask of the prompting routine. You should specify either the 
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address of LIB$GET_INPUT or a routine of your own that has the same 
calling format as LIB$GET_INPUT. This argument must be supplied when 
the HELP command is run in prompting mode (that is, HLP${M—PROMPT is 
set or defaulted). 





DESCRIPTION 
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The LBRS$0UTPUT_HELP routine provides a simple, one-call method to 
initiate an interactive help session. Help library bookkeeping functions, 

such as LBR$INI_-CONTROL and LBR$OPEN, are handled internally. You 
should not call LBR$INI_CONTROL or LBR$OPEN before you issue a call to 
LBR$0UTPUT_HELP. 


LBR$0UTPUT_HELP accepts help keys in the same format as 
LBR$GET_HELP, with the following qualifications: 


e If the keyword HELP is supplied, help text on HELP is output, followed 
by a list of HELP subtopics available. 


If no help keys are provided or if the line_desc argument is 0, a list of 
topics available in the root library is output. 


e If the line_desc argument contains a list of help keys, then each key 
must be separated from its predecessor by a slash (/) or by one or more 
spaces. 


e The first key can specify a library to replace the main library as the root 
library (the first library searched) in which LBR60UTPUT_HELP searches 
for help. A key used for this purpose must have the form <@filespec> , 
where filespec is subject to the same restrictions as the library_name 
argument. If the specified library is an enabled user-defined default 
library, then filespec can be abbreviated as any unique substring of that 
default library’s logical name translation. 


In default library searches, you can define one or more default libraries 
for LBR$0UTPUT_HELP to search for help information not contained in 
the root library. You do this by equating logical names (HLP$LIBRARY, 
HLP$LIBRARY_1, . .. ,HLP$LIBRARY_999) to the file specifications of the 
default help libraries. You can define these logical names in the process, 
group, or system logical name table. 


If default library searching is enabled by the flags argument, LBR5OUTPUT_ 
HELP uses those flags to determine which logical name tables are enabled 
and then automatically searches any user default libraries that have been 
defined in those logical name tables. The library search order proceeds as 
follows: root library, main library (if specified and different from the root 
library), process libraries (if enabled), group libraries (if enabled), system 
libraries (if enabled). If the requested help information is not found in any of 
these libraries, LBR60UTPUT_HELP returns to the root library and issues a 
“help not found” message. 


To enter an interactive help session (after your initial request for help has 
been satisfied), you must set the HLPS4M_PROMPT bit in the flags argument. 


You can encounter four different types of prompt in an interactive help 
session. Each type represents a different level in the hierarchy of help 
available to you: 


1 If the root library is the main library and you are not currently examining 
HELP for a particular topic, the prompt Topic? is output. 
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2 If the root library is a library other than the main library and if you are 
not currently examining HELP for a particular topic, a prompt of the form 
@ <library-spec> Topic? is output. 


3 If you are currently examining HELP for a particular topic (and subtopics), 
a prompt of the form <keyword...> subtopic? is output. 


4 A combination of 2 and 3. 


When you encounter one of these prompt messages, you can respond in any 
one of several ways. Each type of response and its effect on LBRSOUTPUT_ 
HELP in each prompting situation is described in the following table. 


Response 


keyword[... | 


@filespec [keyword[ .. . ]] 


Carriage Return 


CTRL/Z 


Action in the Current Prompt Environment’ 


(1,2) Search all enabled libraries for these keys. 


(3,4) Search additional help for the current topic 
(and subtopic) for these keys. 


(1,2) Same as above, except that the root library 
is the library specified by filespec. |f the specified 
library does not exist, treat @filespec as a normal 
key. 

(3,4) Same as above; treat @filespec as a normal 
key. 

(1,2) Display a list of topics available in the root 
library. 

(3,4) Display a list of subtopics of the current 
topic (and subtopics) for which help exists. 


(1) Exit from LBRSOUTPUT_HELP. 
(2) Change root library to main library. 


(3,4) Strip the last keyword from a list of 
keys defining the current topic (and subtopic) 
environment. 


(1,2,3,4) Exit from LBRSOUTPUT_HELP. 


1Keyed to the prompt in the preceding list. 





CONDITION 
VALUES LBR$_ILLINROU 
RETURNED LBR$_!LLOUTROU 


LBRS_NOHLPLIS 
LBRS6_TOOMNY ARG 
LBRS_USRINPERR 


Input routine improperly specified or omitted. 
Output routine improperly specified or omitted. 
Error. No default help libraries can be opened. 
Error. Too many arguments were specified. 


Error. An error status was returned by the user- 
supplied input routine. 
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LBRSPUT_END Write an End-of-Module Record 


The LBR$SPUT_END routine marks the end of a sequence of records 
written to a library by the LBR5PUT_RECORD routine. 





FORMAT 


LBR$PUT_END _library_index 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENT 


library_index 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_-CONTROL routine. The 
library_index argument is the address of a longword containing the index. 





DESCRIPTION 


Call LBR$PUT_END after you write data records to the library with the 
LBR$PUT_RECORD routine. LBR$6PUT_END terminates a module by 
attaching a 3-byte logical end-of-file record (hexadecimal 77,00,77) to the 
data. 





CONDITION 
VALUES 
RETURNED 
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LBR$_ILLCTL Specified library control index not valid. 
LBR$_LIBNOTOPN Specified library not open. 


Librarian (LBR) Routines 
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LBRS$PUT_HISTORY Write an Update History 


Record 


The LBR$PUT_HISTORY routine adds an update history record to the end 
of the update history list. 





FORMAT 


LBR$PUT_HISTORY library_index ,record_desc 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


library_index 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_-CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 


record_desc 

VMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Library history record. The record_desc argument is the address of a string 
descriptor pointing to the record to be added to the library update history. 





DESCRIPTION 


LBR$PUT_HISTORY writes a new update history record. If the library 
already contains the maximum number of history records (as specified at 
creation time by CRE$L_LUHMAX, see LBR$SOPEN for details), the oldest 
history record is deleted before the new record is added. 
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LBR$PUT_HISTORY 





CONDITION LBR$_NORMAL Normal exit from the routi 
el t from t tine. 
VALUES LBR$_NOHISTORY nee hi , ae inf tional cod 
o update history. is is an informational code, 
RETURNED not an error code. 
LBR$_INTRNLERR Internal librarian error. 
LBR$_RECLNG Record length greater than that specified by 


LBR$SC_MAXRECSIZ. The record was not inserted 
or truncated. 
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LBR$PUT_RECORD 


LBRS$PUT_RECORD Write a Data Record 


The LBR$PUT_RECORD routine writes a data record beginning at the next 
free location in the library. 











FORMAT LBRSPUT_RECORD /ibrary_index ,bufdes ,txtrfa 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS library_index 


VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 


bufdes 

VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor 


Record to be written to the library. The bufdes argument is the address of a 
string descriptor pointing to the buffer containing the output record. 


txtrfa 

VMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: write only 


mechanism: by descriptor 


Record’s file address (RFA) of the module header. The txtrfa argument is the 
address of a 2-longword array receiving the RFA of the newly created module 
header upon the first call to LBR$PUT_RECORD. 


LBR—57 


Librarian (LBR) Routines 
LBRS$PUT_RECORD 





DESCRIPTION If this is the first call to LBR$PUT_RECORD, this routine first writes a module 
header and returns its RFA to the 2-longword array pointed to by txtrfa. 
LBR$SPUT_RECORD then writes the supplied data record to the library. 
On subsequent calls to LBR$PUT_RECORD, this routine writes the data 
record beginning at the next free location in the library (after the previous 
record). The last record written for the module should be followed by a call 
to LBR$PUT_END. 





CONDITION a 
VALU ES LBR$_ILLCTL Specified library control index not valid. 
RETURNED LBR$_LIBNOTOPN Specified library not open. 
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LBRSREPLACE_KEY Replace a Library Key 


The LBR$REPLACE_KEY routine inserts a key in an index by changing the 
pointer associated with an existing key or by inserting a new key. 











FORMAT LBRSREPLACE_KEY _library_index ,key_name ,oldrfa 
/newrta 

RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 

ARGUMENTS library_index 


VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_-CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 


key_name 

VMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Library key (for libraries with ASCII keys). The key_name argument is the 
address of a string descriptor for the key. 


key_name 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library key (for libraries with binary keys). The key_name argument is the 
address of an unsigned longword value for the key. 
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oldrfa 

VMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: write only 


mechanism: by reference 


Old RFA. The oldrfa argument is the address of a 2-longword array 
containing the original RFA (returned by LBR$LOOKUP_KEY) of the module 
header associated with the key you are replacing. 


newrta 

VMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


New RFA. The newrfa argument is the address of a 2-longword array 
containing the RFA (returned by LBR$PUT_RECORD) of the module header 
associated with the new key. 








DESCRIPTION __ If LBR$REPLACE_KEY does not find the key in the current index, it calls the 
LBR$INSERT_KEY routine to insert the key. If LBR$REPLACE_KEY does 
find the key, it modifies the key entry in the index so that it points to the new 
module header. 

es LBR$_ILLCTL Specified lib lind lid 

VALUES ehecee gins sa control index not valid. 

RETURNED yes pecitied library not open. 

LBR$_INVRFA Specified RFA not valid. 
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LBRSRET_RMSSTV Return VMS RMS Status 
Value 


The LBR$RET_RMSSTV routine returns the status value of the last VMS 
Record Management Services (RMS) function performed by any librarian 








subroutine. 
FORMAT LBRSRET_RMSSTV 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS ~ None. 





DESCRIPTION — The LBR$RET_RMSSTYV routine returns, as the status value, the status of the 
last RMS operation performed by the librarian. RMS status codes are defined 
by the $RMSDEF macro in SYS$LIBRARY:STARLET.MLB. 





CONDITION This routine returns any condition values returned by VMS RMS routines. 


VALUES 
RETURNED 
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LBRSSEARCH 


LBRSSEARCH Search an Index 


The LBR$SEARCH routine finds index keys that point to specified data. 





FORMAT 


LBRSSEARCH /ibrary_index ,index_number 
_tfa_to_find ,routine_.name 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 
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library_index 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 


index_number 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Library index number. The index_number argument is the address of 
a longword containing the number of the index you want to search (see 
Section 8.1.2.3). 


_rfa_to_find 


VMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: write only 

mechanism: by reference 


Record’s file address (RFA) of the module whose keys you are searching for. 
The rfa_to_find argument is the address of a 2-longword array containing 
the RFA (returned earlier by LBR6LOOKUP_KEY or LBR$6PUT_RECORD) of 
the module header. 


Librarian (LBR) Routines 
LBRS$SEARCH 


routine_name 

VMS usage: procedure 

type: procedure entry mask 
access: read only 

mechanism: by reference 


Name of a user-supplied routine to process the keys. The routine_name 
argument is the address of the entry mask of a user-supplied routine to call 
for each key entry containing the RFA (in other words, for each key that 
points to the same module header). 


This user-supplied routine cannot contain any calls to LBR6DELETE_KEY or 
LBR$INSERT_KEY. 





DESCRIPTION 


Use LBR$SEARCH to find index keys that point to the same module header. 
Generally, in index number 1 (the module name table), just one key points 
to any particular module; thus, you would probably use this routine only 

to search library indexes where more than one key points to a module. 

For example, you might call LBR$SEARCH to find all the global symbols 
associated with an object module in an object library. 


If LBRSSEARCH finds an index key associated with the specified RFA, it calls 
a user-supplied routine with two arguments: 


e The key argument, which is the address of either of the following: 
- A string descriptor for the keyname (libraries with ASCII keynames). 
- An unsigned longword for the key value (libraries with binary keys). 


e The RFA argument, which is the address of a 2-longword array containing 
the RFA of the module header. 


The routine must return a value to indicate success or failure. If the specified 


routine returns a false value (low bit = 0), then the index search terminates. 


Note that the key found by LBR$SEARCH is valid only during the call to the 
user-supplied routine. If you want to use the key later, you must copy it. 





CONDITION 
VALUES 
RETURNED 


LBR$_ILLCTL Specified library control index not valid. 

LBR$_ILLIDXNUM Specified library index number not valid. 

LBR$_KEYNOTFND Librarian did not find any keys with the specified 
RFA. 

LBR$_LIBNOTOPN Specified library not open. 
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LBRSSET_INDEX 


LBRSSET_INDEX Set the Current Index Number 


The LBR$SET_INDEX routine sets the index number to use when 
processing libraries that have more than one index. 





FORMAT 


LBR$SSET_INDEX | /ibrary_index ,index_number 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


library_index 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 


index_number 


VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Index number you want to establish as the current index number. The 
library_index is the address of the longword that contains the number of the 
index you want to establish as the current index. (See Section 8.1.2.3.) 





DESCRIPTION 
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When you call LBR$INI_-CONTROL, the librarian sets the current library 
index to 1 (the module name table, unless the library is a user-developed 
library). If you need to process another library index, you must use 
LBR$SET_INDEX to change the current library index. 


Note that macro, help, and text libraries contain only one index; therefore, 
you do not need to call LBR$SET_INDEX. Object libraries contain two 
indexes. If you want to access the global symbol table, you must call the 
LBR$SET_INDEX routine to set the index number. User-developed libraries 
can contain more than one index; therefore, you may need to call 
LBR$SET_INDEX to set the index number. 


Upon successful completion, LBR$SET_INDEX sets the current library index 
to the requested index number. The librarian routines number indexes 
starting with 1. 


Librarian (LBR) Routines 
LBR$SET_INDEX 





CONDITION eeeaneay Sait bes - 
t t : 

VALUES a ao i : rary rol in oe va “ 
me ‘ . 

RETURNED ibrary index number specified not vali 


LBR$_LIBNOTOPN Specified library not open. 
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LBR$SET_LOCATE 


LBRSSET_LOCATE Set Record Access to Locate 
Mode 


The LBR$SET_LOCATE routine sets the record access of librarian 
subroutines to locate mode. 








FORMAT LBRS$SET_LOCATE _/ibrary_index 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENT library_index 
VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 





DESCRIPTION Librarian record access may be set to move mode (the default set by 
LBR$SET_MOVE) or locate mode. The setting affects the operation of the 
LBR$GET_RECORD routine. 


If move mode is set (the default), LBRS5GET_RECORD copies the requested 
record to the specified user buffer. If locate mode is set, the record is not 
copied. Instead, the outbufdes descriptor is set to reference the internal 
librarian subroutine buffer that contains the record. 





CONDITION a | | 
VALUES LBR$_ILLCTL Specified library control index not valid. 
RETURNED LBR$_LIBNOTOPN Specified library not open. 
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LBR$SET_MODULE 


LBRSSET_MODULE Read or Update a Module 


Header 


The LBR$SET_MODULE routine reads, and optionally updates, the module 
header associated with a given record's file address (RFA). 











FORMAT LBRS$SET_MODULE library_index ,rfa [, bufdesc] 
[,buflen] [, updatedesc] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 

access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 

ARGUMENTS library_index 


VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 


rfa 

VMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: write only 


mechanism: by reference 


Record’s. file address (RFA) associated with the module header. The rfa 
argument is the address of a 2-longword array containing the RFA returned 
by LBR$PUT_RECORD or LBR$LOOKUP_KEY. 


bufdesc 

VMS usage: char_string 
type: character string 
access: write only 


mechanism: by descriptor 


Buffer that receives the module header. The bufdesc argument is the address 
of a string descriptor pointing to the buffer that receives the module header. 
The buffer must be the size specified by the symbol MHD$B_USRDAT plus 
the value of the CRE$L_UHDMAx create option. The MHD$ and CRE$ 
symbols are defined in the modules $MHDDEF and $CREDEF, which are 
stored in SYS$LIBRARY:STARLET.MLB. 
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buflen 

VMS usage: longword_signed 
type: longword (signed) 
access: write only 


mechanism: by reference 


Length of the module header. The buflen argument is the address of a 
longword receiving the length of the returned module header. 


updatedesc 

VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor 


Additional information to be stored with the module header. The updatedesc 
argument is the address of a string descriptor pointing to additional data that 
the librarian stores with the module header. If you include this argument, the 
librarian updates the module header with the additional information. 





DESCRIPTION 


If you specify bufdesc, the librarian routine returns the module header 
into the buffer. If you specify buflen, the librarian routine also returns the 
buffer’s length. If you specify updatedesc, the routine updates the header 
information. 


You define the maximum length of the update information (by specifying 

a value for CRE$L_UHDMAX) when you create the library. The librarian 
zero-fills the information if it is less than the maximum length or truncates it 
if it exceeds the maximum length. 





CONDITION 
VALUES 
RETURNED 
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LBR$_HDRTRUNC Buffer supplied to hold the module header was too 
small. 

LBR$ILLCTL Specified library control index not valid. 

LBR$_ILLOP Error. The updatedesc argument was supplied 


and the library was a Version 1.0 library or the 
library was opened only for read access. 


LBR$_INVRFA Specified RFA does not point to a valid module 
header. 
LBR$_LIBNOTOPN - Specified library not open. 


Librarian (LBR) Routines 
LBR$SET_MOVE 


LBRSSET_MOVE Set Record Access to Move 
Mode 


The LBR$SET_MOVE routine sets the record access of Librarian 
subroutines to move mode. 








FORMAT LBR$SSET_MOVE _library_index 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENT library_index 
VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_-CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 





DESCRIPTION Librarian record access may be set to move mode (the default, set by 
LBR$SET_MOVE) or locate mode. The setting affects the operation of the 
LBR$GET_RECORD routine. If move mode is set, LBR$6GET_RECORD 
copies the requested record to the specified user buffer. For details, see the 
description of LBR$6GET_RECORD. 





CONDITION a | | 
VALUES LBR$_ILLCTL Specified library control index not valid. 
RETURNED LBR$_LIBNOTOPN Specified library not open. 
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9.1 Introduction to NCS Routines 


This section describes the National Character Set (NCS) Utility routines. The 
NCS Utility provides a common facility for defining and accessing collating 
sequences and conversion functions. Collating sequences are used to compare 
strings for sorting purposes. Conversion functions are used to derive an 
altered form of an input string based on an appropriate conversion algorithm. 


Using NCS, you can formulate collating sequences and conversion functions, 
and register them in an NCS library. The NCS routines provide a 
programming interface to NCS that allows you to access the collating 
sequences and conversion functions from an NCS library for doing string 
comparisons. . 


Typically, NCS collating sequences are selective subsets of the multinational 
character set. They are used extensively in programming applications 
involving various national character sets. For example, a program may 

use the Spanish collating sequence to assign appropriate collating weight to 
characters from the Spanish national character set. Another program may 
use the French collating sequence to assign appropriate collating weight to 
characters in the French national character set. 


In addition to providing program access to collating sequences and conversion 
functions in an NCS library, the NCS routines provide a means for saving 
definitions in a local file for subsequent use by the comparison and conversion 
routines. 


Table 9-1 lists the NCS routines. 
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Table 9-1 NCS Routines 


Routine 


NCS$COMPARE 


NCS$CONVERT 
NCS$END_CS 


NCS$END_CF 


NCS$GET_CF 


NCS$GET_CS 


NCS$RESTORE_CF 


NCS$RESTORE_CS 


NCS$SAVE_CF 


NCS$SAVE_CS 


Description 

Compares two strings using specified collating sequence 
as comparison basis 

Converts a string using the specified conversion function 


Terminates the use of a collating sequence by the calling 
program 

Terminates the use of a conversion function by the 
calling program 


Retrieves the definition of the named conversion function 
from the NCS library 


Retrieves the definition of the named collating sequence 
from the NCS library 


Permits the calling program to restore the definition of a 
“saved” conversion function from a data base or an RMS 
file 
Permits the calling program to restore the definition of a 
“saved” collating sequence from a data base or an RMS 
file 


Provides the calling program with information that 


permits the application to store the definition of a 


conversion function in a local data base or an RMS file 


Provides the calling program with information that 
permits the application to store the definition of a 
collating sequence in a local data base or an RMS file 


In a typical application, the program does the following: 


1 Prepares a string for comparison 


2 Makes a call to the NCS$GET routine specifying the appropriate collating 


sequence 


3 Makes one or more calls to the NCS$COMPARE routine which does the 


actual comparison 


4 Terminates the comparison with a call to the NCS$END routine 


The program may also include the use of conversion functions in preparation 
for the comparison routines. 
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Examples of How to Use NCS Utility Routines 


This section includes two examples of how to use NCS utility routines in 
program applications. Example 9-1 illustrates the use of NCS utility routines 


in a FORTRAN program. 


Example 9-1 Using NCS Routines in a FORTRAN Program 





aan 


Qa Qn 


Qa Q 


CSSTRING,STRING1 ,STRING2 
CSLENGTH , LENGTH1 , LENGTH2 , CSID , STATUS , RESULT 
NCS$GET_CS , NCS$COMPARE , NCS$END_CS 


CMP (3) 


CMP (1) 
CMP (2) 
CMP (3) 


1<¢! 


I>! 


Read the name of the collating sequence. 


READ (5,15,END=999) CSLENGTH ,CSSTRING 
FORMAT(' Collating Sequence: ') 


Get the collating sequence from the NCS library. 


CSID = 0 
STATUS = NCS$GET_CS (CSID, CSSTRING(1:CSLENGTH)) 
IF ((STATUS .AND. 1) .NE. 1) THEN 

CALL LIB$SIGNAL (%VAL(STATUS) ) 

ENDIF 


Read two strings to be compared according to the collating sequence. 


READ (5,15,END=999) LENGTH1,STRING1 
WRITE (6,20) 
READ (5,15,END=999) LENGTH2,STRING2 


IF (LENGTH1 .EQ. 0 .AND. LENGTH2 .EQ. 0) THEN 
GOTO 200 
ENDIF 


FORMAT(' String1: ') 

FORMAT(' String2: ') 

FORMAT (Q,A80) 

Compare the strings. 

RESULT = NCS$COMPARE (CSID, STRING1(1:LENGTH1), STRING2(1:LENGTH2) ) 
Display the results of the comparison. 

FORMAT(' ',A,' ',A,' ',A) 

GOTO 100 


Example 9-1 Cont'd. on next page 
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Example 9-1 (Cont.) Using NCS Routines in a FORTRAN Program 


Come here if both inputs are blank -- we are done. 
Call NCS$END_CS to free any storage used to hold the CS. 


NQAQQ 


00 STATUS = NCS$END_CS (CSID, CSSTRING(1:CSLENGTH) ) 
IF ((STATUS .AND. 1) .NE. 1) THEN 
CALL LIB$SIGNAL (%VAL(STATUS) ) 
ENDIF 
CALL EXIT 


999 CONTINUE 
END 


Example 9-2 illustrates the use of NCS routines from a MACRO-32 program. 


Example 9-2 Using NCS Routines in a MACRO-32 Program 





.TITLE /NCS Conversion Function Example/ 


$NAMDEF 

.PSECT DATA LONG,NOEXE, WRT 
CFID: . LONG 
LENGTH: .WORD 
CFNAME_D: 

-ASCID /EDT_VT2xx/ 
PROMPT_D: 

.ASCID /_File: / 
SIZE = 1024 


.ALIGN LONG 
INFAB: $FAB FNA=F ILE, FNS=NAM$C_MAXRSS 
INRAB: $RAB FAB=INFAB , UBF=REC , USZ=SIZE 


FILE: .BLKB NAM$C_MAXRSS 
FILE_D: .LONG NAM$C_MAXRSS 


.ADDRESS - 
FILE 
REC: .BLKB SIZE 
REC_D: 
.LONG SIZE 
.ADDRESS - 
REC 
DEST: 
-BLKB SIZE 
DEST_D: .LONG SIZE 
.ADDRESS - 
DEST 


.PSECT CODE EXE, NOWRT 
-ENTRY NCS$EXAMPLE, “M<> 


Example 9-2 Cont'd. on next page 


NCS—4 


National Character Set (NCS) Utility Routines 
9.2 Examples of How to Use NCS Utility Routines 


Example 9-2 (Cont.) Using NCS Routines in a MACRO-32 Program 


; Get the EDT_VT2xx conversion function from default library. 
PUSHAL CFNAME_D 
PUSHAL CFID 
CALLS #2,G°NCS$GET_CF 
BSBW ERROR 


; Get the file to be converted. 


PUSHAL LENGTH 

PUSHAL PROMPT_D 

PUSHAL FILE_D 

CALLS #3,G°LIB$GET_INPUT 
BSBW ERROR 

MOVW LENGTH, FILE_D 


; Open the file to be converted. 


$OPEN FAB=INFAB 
BSBW ERROR 
$CONNECT RAB=INRAB 
BSBW ERROR 


; Read each record from the file. 


LOOP : $GET RAB=INRAB 
BLBC RO, STATUS 


; Call NCS$CONVERT to convert the input string to EDT fallback. 
; (e.g., Convert form feed to <FF>, escape to <ESC>, etc...) 


MOVW INRAB+RAB$W_RSZ,REC_D 
PUSHAL LENGTH 

PUSHAL DEST_D 

PUSHAL REC_D 

PUSHAL CFID 

CALLS #4,G°NCS$CONVERT 

BSBW ERROR 

MOVW LENGTH , DEST_D 


; Write result to SYS$OQUTPUT. 
PUSHAL DEST_D 
CALLS #1,G°LIB$PUT_OUTPUT 


MOVW #SIZE, DEST_D 
BRB LOOP 


Example 9-2 Cont'd. on next page 
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Example 9-2 (Cont.) Using NCS Routines in a MACRO-32 Program 


STATUS: CMPL RO, #RMS$_EOF 
BEQL DONE 
BSBW ERROR 


; Call NCS$END_CF to free any storage used to hold the conversion function. 


DONE: PUSHAL CFID 
CALLS #1,G°NCS$END_CF 
BSBW ERROR 
RET 


; Error handling. 


ERROR: BLBC RO, 10$ 
RSB 


10$: $EXIT_S RO 
.END NCS$EXAMPLE 





NCS Routines 
The following pages describe the NCS routines. 
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NCSSCOMPARE Compare Strings 


The NCS$COMPARE routine compares two strings using a specified 
collating sequence as a comparison basis. 








FORMAT NCS$COMPARE cs_dd, string_1, string_2 
RETURNS VMS usage: integer 

type: longword integer (signed) 

access: write only 


mechanism: by value 


Longword condition value. Most routines return a condition value in RO but 
the NCS$¢COMPARE routine uses RO to return the result of the comparison, 
as shown in the following table. 


Returned Value Comparison Result 

—1 string_1 is less than string_2 

0 string_1 is equal to string_2 

1 string_1 is greater than string_2 


The NCS$COMPARE routine uses the VAX Signaling Mechanism to indicate 
completion status as described under CONDITION VALUE SIGNALED. 





ARGUMENTS cs_id 
VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Address of a longword that NCS uses to identify a collating sequence. The 
cs_id argument is required, and can be obtained by a call to the 
NCS$GET_CS routine. is 


All calls to the NCS$¢COMPARE routine and the call to the NCS$END_CS 
routine that terminates the comparison must pass this longword identifier. 

Upon completion, the NCS$END_CS routine releases the memory used to 
store the collating sequence and sets the value of the longword identifier to 


Zero. 

string_1 

VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor 


Descriptor (length and address) of the first string. 
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string_2 

VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor 


Descriptor of the second string. 





DESCRIPTION The NCS$COMPARE routine compares two strings using the specified 
collating sequence as the comparison basis. The routine indicates whether the 
value of the first string is greater than, less than, or equal to the value of the 
second string. 





CONDITION . 

VALUE STR$_ILLSTRCLA Illegal string class. Severe error. The descriptor 
of string_1 or string_2, or both, contains a class 

SIGNALED code not supported by the VAX Procedure Calling 


and Condition Handling Standard. 
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NCS$CONVERT 


NCS$CONVERT Convert String 


The NCS$CONVERT routine converts a string using the specified 
conversion function. 





FORMAT 


NCS$CONVERT cf_id, source, dest [,ret_length] 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 


LBR messages (prefaced by an NCS message) may signal errors detected 
while the process is accessing the NCS library. 





ARGUMENTS 


cf_id 

VMS usage: longword_signed 

type: longword integer (signed) 
access: read only 

mechanism: by reference 


Address of a longword that NCS uses to identify a conversion function. The 
cf_id argument is required, and can be obtained by a call to the 
NCS$GET_CF routine. 


All calls to the NCS$CONVERT routine and the call to the NCS$END_CF 
routine that terminates the conversion must pass this longword identifier. 
Upon completion, the NCS$END_CF routine releases the memory used to 
store the conversion function and sets the value of the longword identifier to 
zero. 


source 

VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor 


Descriptor of source string. 


dest 

VMS usage: char_string 
type: character string 
access: write only 


mechanism: by descriptor 


Descriptor of destination string. 
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ret_length 

VMS usage: word unsigned 
type: word (unsigned) 
access: write only 
mechanism: by reference 


Length of converted string. 





DESCRIPTION _ Using the specified conversion function, the NCS$CONVERT routine converts 
the source string and stores the result in the specified destination. Optionally, 
the calling program may request that the routine return the length of the 
converted string. 





CONDITION rmaete ) 
=. _ t 

VALUES pail identifier does not refer to a conversion 

peer SS$_NORMAL Successful completion. 


LIB$_STRTRU Successful completion. However, the resultant 
string was truncated because the storage allocation 
for the destination string was inadequate. 
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NCSS$END_CF 


NCS$END_CF End Conversion Function 


The NCS$END_CF routine terminates a conversion function. 





FORMAT 


NCS$END_CF cf_id 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENT 


cf_id 

VMS usage: longword_signed 

type: longword integer (signed) 
access: modify 

mechanism: by reference 


Address of a longword that NCS uses to store a nonzero value identifying a 
conversion function. 


The cf_id argument is required. 





DESCRIPTION 


The NCS$END-_-CF routine indicates to NCS that the calling program no 
longer needs the conversion function. NCS releases the memory space 
allocated for the coversion function and sets the value of the longword 
identifier to zero. 





CONDITION 
VALUES 
RETURNED 


NCS$_NORMAL Normal successful completion. The longword 
identifier value is set to zero. 


NCS$_NOT_CF Name of identifier does not refer to a conversion 
function. 
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NCSS$END_CS._ End Collating Sequence 


The NCS$END_CS routine terminates a collating sequence. 








FORMAT — NCS$END_CS_ cs_id 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENT cs_id 
VMS usage: longword_signed 
type: longword integer (signed) 
access: modify 
mechanism: by reference 


Address of a longword that NCS uses to store a nonzero value identifying a 
collating sequence. 


The cs_id argument is required. 





DESCRIPTION — The NCS$END_CS routine indicates to NCS that the calling program no 
longer needs the collating sequence. NCS releases the memory space 
allocated for the collating sequence and sets the value of the longword 
identifier to zero. 





CONDITION 


NCS$_NORMAL Normal successful completion. The longword 
VALUES : P 9 


identifier value is set to zero. 
RETURNED NCS$_NOT_CS Name of identifier does not refer to a collating 


sequence. 
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NCS$GET_CF Get Conversion Function 


The NCS$GET_CF routine retrieves the definition of the named conversion 
function from the NCS library. 








FORMAT NCS$GET_CF cf_id/,cfname], librar] 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 


LBR messages (prefaced by an NCS message) may signal errors detected 
while the process is accessing the NCS library. 





ARGUMENTS cf_id 
VMS usage: longword_signed 
type: longword integer (signed) 
access: modify 
mechanism: by reference 


Address of a longword used by NCS to identify a conversion function. 

The calling program must ensure that the longword contains zero before 
invoking the NCS$GET_CF routine because the routine stores a nonzero 
value in the longword. The nonzero value identifies the conversion function. 
All subsequent calls to the NCS$CONVERT routine and the call to the 
NCS$END_CF routine to terminate the conversion function pass the 
longword identifier. When it completes the conversion, the 

NCS$END_CF routine releases the memory used to store the conversion 
function and sets the value of the longword identifier to zero. 


The conversion function identifier enhances modular programming and 
permits concurrent use of multiple conversion functions within a program. 


The calling program should not attempt to interpret the contents of the 
longword identifier. 


The cf_id argument is required. 


cfname 

VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor 


Name of the conversion function being retrieved. 
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NCS$GET_CF 
librar 
VMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 
Name of the library where the conversion function is stored. 
DESCRIPTION The NCS$GET_CF routine extracts the named conversion function from the 
specified NCS library. 
If the calling program omits the cfname argument, an “identity” conversion 
function padded with NUL characters (hex 0) is provided. The identity 
conversion function effectively leaves each character unchanged by converting 
each character to itself. For example, A becomes A, B becomes B, C becomes 
C, and so forth. 
If the calling program omits the librar argument, NCS accesses the default 
NCS library. 
CONDITION NCS$_DIAG O i leted with signalled di i 
a t t t tics. 
VALUES mongeees oe ipa aie wi se ed diagnos ee 
a! cl t t t 
RETURNED ale identifier does not refer to a conversion 
NCS$_NOT_FOUND Name of identifier not found in the NCS library. 
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NCS$GET_CS_ Get Collating Sequence 


The NCS$GET_CS routine retrieves the definition of the named collating 
sequence from the NCS library. 








FORMAT NCS$GET_CS_ cs_id[,csname], librar] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 


LBR messages (prefaced by an NCS message) may signal errors detected 
while the process is accessing the NCS library. 





ARGUMENTS cs_id 
VMS usage: longword_signed 
type: longword integer (signed) 
access: modify 
mechanism: by reference 


Address of a longword that NCS uses to store a nonzero value identifying 
a collating sequence. The calling program must ensure that the longword 
identifier contains zero before invoking the NCS$GET_CS routine. 


All subsequent calls to the NCS$COMPARE routine and the call to the 
NCS$END_CS routine that terminates the use of the collating sequence 
must pass this longword identifier. Upon completion of the comparisons, 
the NCS$END_CS routine releases the memory used to store the collating 
sequence and sets the value of the longword identifier to zero. 


The collating sequence identifier enhances modular programming and permits 
concurrent use of multiple collating sequences within a program. 


The calling program should not attempt to interpret the contents of the 
longword identifier. 


The cs_id argument is required. 


csname 

VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor 


Name of the collating sequence being retrieved. 


NCS-15 


National Character Set (NCS) Utility Routines 
NCS$GET_CS 


librar 

VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor 


File specification of the library where the collating sequence is stored. 





DESCRIPTION The NCS$GET_CS routine extracts the named collating sequence from the 
specified NCS library. If the calling program omits the csname argument, 
NCS creates a collating sequence that uses the “native” collating sequence 
as a basis for the comparisons. This collating sequence is padded with NUL 
characters (hex 0). 


If the calling program omits the librar argument, NCS accesses the default 
NCS library. 





CONDITION NCS$_DIAG O i leted with signalled di 
ik t t t tics. 
VALUES oe saa ee wi ae e ai ics 
—NOT_ ame of identifier does not refer to a collating 
RETURNED ecenence 
NCS$_NOT_FOUND Name of identifier not found in the NCS library. 
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NCS$RESTORE_CF Restore Conversion Function 


The NCS$RESTORE_CF routine permits the calling program to restore the 
definition of a saved conversion function from a database or a file. 








FORMAT NCS$RESTORE_CF  cf_id/,length]/, address] 
RETURNS VMS usage: cond_value 

type: ~ longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. The condition value that this routine can return is listed under 
CONDITION VALUE RETURNED. 


LBR messages (prefaced by an NCS message) may signal errors detected 
while the process is accessing the NCS library. 





ARGUMENTS cf_id 2 
VMS usage: longword_signed 
type: longword integer (signed) 
access: write only 
mechanism: by reference 


Address of a longword that NCS uses to identify a conversion function. 


The cf_id argument is required. 


length 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Longword that the calling program uses to indicate the length of the 
conversion function being restored. 


address 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Longword that the calling program uses as a pointer to the conversion 
function being restored. 
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DESCRIPTION — The NCS$RESTORE_CF routine, used in conjunction with the 
NCS$SAVE_CF routine, permits the application program to keep a local copy 
of the conversion function. The NCS$SAVE_CF routine obtains the length 
and location of the conversion function and returns it to the application 
program. The application program subsequently provides this information 
to the NCS$RESTORE_CF routine, which uses it to access the conversion 
function. 


This routine also does some integrity checking on the conversion function as 
it is being processed. 





CONDITION wen 
VALUE NCS$_NOT_CF ee identifier does not refer to a conversion 
RETURNED | 
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NCS$RESTORE_CS Restore Collating Sequence 


The NCS$RESTORE_CS routine permits the calling program to restore the 
definition of a “saved” collating sequence from a database or a file. 








FORMAT NCS$RESTORE_CS  cs_id/,lengthj[,address] 
RETURNS VMS usage: cond_value 
. type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. The condition value that this routine can return is listed under 
CONDITION VALUE RETURNED. 


LBR messages (prefaced by an NCS message) may signal errors detected 
while the process is accessing the NCS library. 





ARGUMENTS cs_id 
VMS usage: longword_signed 
type: longword integer (signed) 
access: write only 
mechanism: by reference 


Address of a longword that NCS uses to identify a collating sequence. 


The cs_id argument is required. 


length 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Longword that the calling program uses to indicate the length of the collating 
sequence being restored. 


address 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Longword that the calling program uses as a pointer to the collating sequence 
being restored. 
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DESCRIPTION — The NCS$RESTORE_CS routine, used in conjunction with the 
NCS$SAVE_CS routine, permits the application program to keep a local 
copy of the collating sequence. The NCS$SAVE_CS routine obtains the 
length and location of the collating sequence and returns it to the application 
program. The application program subsequently provides this information 
to the NCS$RESTORE_CS routine, which uses it to access the collating 
sequence. 


This routine also does some integrity checking on the collating sequence as it 
is being processed. 





CONDITION ne ae 
VALUE NCS$_NOT_CS eee does not refer to a collating 
RETURNED ahs 
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NCSSSAVE_CF Save Conversion Function 


The NCS$SAVE_CF routine provides the calling program with information 
that permits the application to store the definition of a conversion function 
in a local database or a file rather than in the NCS library. 








FORMAT NCS$SAVE_CF  cf_id/,lengthj/, address] 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. The condition value that this routine can return is listed under 
CONDITION VALUE RETURNED. 


LBR messages (prefaced by an NCS message) may signal errors detected 
while the process is accessing the NCS library. 





ARGUMENTS cf_id 
VMS usage: longword_signed 


type: longword integer (signed) 
access: read only 
mechanism: by reference 


Address of a longword that NCS uses to identify a conversion function. 


The cf_id argument is required. 


length 

VMS usage: longword_unsigned 
type: | longword (unsigned) 
access: write only 


mechanism: by reference 


Longword used to store the length of the specified conversion function. 


address 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 


mechanism: by reference 


Longword used to store the address of the specified conversion function. 
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NCS$SAVE_CF 





DESCRIPTION 


The NCS$SAVE_CF routine, used in conjunction with the 
NCS$_RESTORE_CF routine, permits the application program to store 
a conversion function definition in a local file or in a database. When 
the calling program specifies the conversion function identifier, NCS 
returns the location of the definition and its length in bytes, permitting 
the calling program to store the definition locally, rather than in an NCS 
library. Subsequently, the application supplies this information to the 
NCS$RESTORE_CF routine, which restores the conversion function to a 
form that can be used by the NCS$CONVERT routine. 


This routine also does some integrity checking on the conversion function as 
it is being processed. 





CONDITION 
VALUE 
RETURNED 
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NCS$_NOT_CF Name of identifier does not refer to a conversion 
function. 


National Character Set (NCS) Utility Routines 
NCS$SAVE_CS 


NCS$SAVE_CS Save Collating Sequence 


The NCS$SAVE_CS routine provides the calling program with information 
that permits the application program to store the definition of a collating 
sequence in a database or a file rather than in the NCS library. 








FORMAT NCS$SAVE_CS _ cs_id/,length][, address] 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. The condition value that this routine can return is listed under 
CONDITION VALUE RETURNED. 


LBR messages (prefaced by an NCS message) may signal errors detected 
while the process is accessing the NCS library. 


ARGUMENTS cs_id 

VMS usage: longword_signed 

type: longword integer (signed) 
access: read only 

mechanism: by reference 





Address of a longword that NCS uses to identify a collating sequence. 


The cs_id argument is required. 


length 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 


mechanism: by reference 


Longword that NCS uses to indicate the length of the specified collating 
sequence to the calling program. 


address 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 


mechanism: by reference 


Longword that NCS uses to indicate the address of the specified collating 
sequence to the calling program. 
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NCSSSAVE_CS 





DESCRIPTION 


The NCS$SAVE_CS routine, used in conjunction with the 
NCS$_RESTORE_CS routine, permits the application program to store a 
collating sequence definition in a local file or in a database. When the calling 
program specifies the collating sequence identifier, NCS returns the location 
of the definition sequence and its length in bytes, permitting the calling 
program to store the definition locally, rather than in a library. Subsequently, 
the application supplies this information to the NCS$RESTORE_CS routine, 
which restores the collating sequence to a form that can be used by the 
NCS$COMPARE routine. 


This routine also does some integrity checking on the collating sequence as it 
is being processed. 





CONDITION 
VALUE 
RETURNED 
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NCS$_NOT_CS Name of identifier does not refer to a collating 
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10.1 Introduction to PSM Routines 


The print symbiont modification (PSM) routines allow you to modify the 
behavior of the print symbiont supplied with the VMS operating system. 


The VMS print symbiont processes data for output to standard line printers 
and printing terminals by performing the following functions: 


¢ Reading the data from disk 

¢ Formatting the data 

e Sending the data to the printing device 

¢ Composing separation pages (flag, burst, and trailer pages) and inserting 
them into the data stream for printing 

Some of the reasons for modifying the print symbiont include the following: 


¢ To include additional information on the separation pages (flag, burst, 
and trailer) or to format them differently 


¢ To filter and modify the data stream sent to the printer 


e To change some of the ways that the symbiont controls the printing 
device 


You may not always be able to modify the print symbiont to suit your needs. 
For example, you cannot do the following: 


¢ Modify the VMS symbiont’s control logic or the sequence in which the 
symbiont calls routines. 


¢ Modify the interface between the VMS symbiont and the job controller. 


If you cannot modify the VMS print symbiont to suit your needs, you may 
want to write your own symbiont. Section 10.3 describes how to write your 
own symbiont and integrate it with the VMS operating system. However, 
you should modify the VMS print symbiont, when possible, rather than write 
your own symbiont. 


The rest of this chapter contains the following information about PSM 
routines: 


e¢ Section 10.2 contains an overview of the VMS print symbiont and of 
symbionts in general. It explains concepts such as “symbiont streams’; 
describes the relationship between a symbiont, a device driver, and 
the job controller; and gives an overview of the VMS print symbiont’s 
internal logic. 


This section is recommended for those who want to either modify the 
VMS print symbiont or write a new symbiont. 


PSM-1 


Print Symbiont Modification (PSM) Routines 
10.1 Introduction to PSM Routines 


¢ Section 10.3 details the procedure for modifying the VMS print symbiont. 
It includes an overview of the entire procedure, followed by a detailed 
description of each step. 


¢ Section 10.4 contains an example of a simple modification to the VMS 
print symbiont. 


¢ Section 10.5 describes each PSM routine and the interface used by the 
routines you substitute for the standard PSM routines. 





10.2. VMS Print Symbiont Overview 


The VMS operating system supplies two symbionts: a print symbiont, which 
is an output symbiont, and a card reader, which is an input symbiont. An 
output symbiont receives tasks from the job controller, whereas an input 
symbiont sends jobs to the job controller. The card reader symbiont cannot 
be modified. You can modify the print symbiont, described in this section, 
using PSM routines. 


There are two types of output symbiont: device and server. A device 
symbiont processes data for output to a device, for example, a printer. A 
server symbiont also processes data but not necessarily for output to a 
device, for example, a symbiont that copies files across a network. The VMS 
operating system supplies no server symbionts. 


10.2.1 Components of the VMS Print Symbiont 


The VMS print symbiont includes the following major components: 
e PSM routines that are used to modify the print symbiont 


¢ Routines that implement input, format, and output services in the VMS 
print symbiont 


¢ Routines that implement the internal logic of the VMS print symbiont 


The VMS print symbiont is implemented using the Symbiont Services Facility. 
This facility provides communication and control between the job controller 
and symbionts through a set of Symbiont/Job-Controller Interface Routines 
(SMB routines), which are documented in Chapter 11. 


All of these routines are contained in a shareable image with the file 
specification SYS$SHARE:SMBSRVSHR.EXE. 


10.2.2 Creation of the Print Symbiont Process 
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The print symbiont is a device symbiont, receiving tasks from the job 
controller and processing them for output to a printing device. In the VMS 
operating system, the existence of a print symbiont process is linked to the 
existence of at least one print execution queue that is started. 


The job controller creates the print symbiont process by calling the Create 
Process (6CREPRC) system service; it does this whenever either of the 
following conditions occur: 
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e A print execution queue is started (from the stopped state) and no 
symbiont process is running the image specified with the START /QUEUE 
command. 


A print execution queue is started by means of the DCL command START 
/QUEUE. You can use the /PROCESSOR qualifier with the START 
/QUEUVE command to specify the name of the symbiont image that is to 
service an execution queue; if you omit /PROCESSOR, then the default 
symbiont image is PRTSMB. 


¢ Currently existing symbiont processes suited to a print execution queue 
cannot accept additional devices; that is, the symbionts have no more 
available streams. In such a case, the job controller creates another print 
symbiont process. The next section discusses symbiont streams. 


The print symbiont process runs as a detached process. 


10.2.3 Symbiont Streams 


A stream is a logical link between a print execution queue and a printing 
device. When the queue is started (by means of START/QUEUE), the 

job controller creates a stream linking the queue with a symbiont process. 
Because each print execution queue has a single associated printing device 
(specified with the /ON=device_name qualifier in the INITIALIZE/QUEUE or 
START/QUEUVE command), each stream created by the job controller links a 
print execution queue, a symbiont process, and the queue’s associated printer. 


A symbiont that can support multiple streams simultaneously (that 

is, multiple print execution queues and multiple devices) is termed a 
multithreaded symbiont. The job controller enforces an upper limit of 16 
on the number of streams that any symbiont can service simultaneously. 


Therefore, in the VMS operating system environment, only one print 
symbiont process is needed as long as the number of print execution queues 
(and associated printers) does not exceed 16. If there are more than 16 print 
execution queues, the job controller creates another print symbiont process. 


The VMS print symbiont is, therefore, a multithreaded symbiont that can 
service aS many as 16 queues and devices, but you can modify it to service 
any number of queues and devices as long as the number is less than or equal 
to 16. 


A symbiont stream is said to be “active” when a queue is started on that 
stream. The print symbiont maintains a count of active streams. It increments 
this count each time a queue is started and decrements it when a queue is 
stopped with the DCL command STOP/QUEUE/NEXT or STOP/QUEUE 
/RESET. When the count falls to zero, the symbiont process exits. The 
symbiont does not decrement the count when the queue is paused by STOP 
/ QUEUE. 


Figure 10-1 shows the relationship of generic print queues, execution print 
queues, the job controller, the print symbiont, printer device drivers, and 
printers. The dotted lines connecting the boxes denote streams. 
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Figure 10-1 Multithreaded Symbiont 
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10.2.4 Symbiont and Job Controller Functions 


This section compares the roles of the symbiont and job controller in the 
execution of print requests. You issue print requests using the PRINT 
command. 


The job controller uses the information specified on the PRINT command line 
to determine the following: 


Which queue to place the job in (/QUEUE, /REMOTE, /LOWERCASE, 
and /DEVICE) 


How many copies to print (/COPIES and /JOB_COUNT) 


Scheduling constraints for the job (/PRIORITY, /AFTER, 
/BLOCK_LIMIT, /HOLD, /FORM, /CHARACTERISTICS, and 
/ RESTART) 


How and whether to display the status of jobs and queues (/NOTIFY, 
/OPERATOR, and /IDENTIFY) 


The print symbiont, on the other hand, interprets the information supplied 
with the qualifiers that specify this information: 
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Whether to print file separation pages (/BURST, /FLAG, and /TRAILER) 


Information to include when printing the separation pages (/NAME and 
/ NOTE) 


Which pages to print (/PAGES) 
How to format the print job (/FEED, /SPACE, and /PASSALL) 
How to set up the job (/SETUP) 


10.2.5 Print Symbiont In 
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The print symbiont, not the job controller, performs all necessary device- 
related functions. It communicates with the printing device driver. For 
example, when a print execution queue is started (by means of START 
/QUEUE/ONFdevice_name) and the stream is established between the 
queue and the symbiont, the symbiont parses the device name specified by 
the /ON qualifier in the START/QUEUE command, allocates the device, 
assigns a channel to it, obtains the device characteristics, and determines the 
device class. In versions of the VMS operating system prior to Version 4.0, 
the job controller performed these functions. 


The print symbiont’s output routine returns an error to the job controller if 
the device class is neither printer nor terminal. 


ternal Logic 


The job controller deals with units of work called jobs, while the print 
symbiont deals with units of work called tasks. A print job can consist of 
several print tasks. Thus, in the processing of a print job, the job controller’s 
role is to divide a print job into one or more print tasks, which the symbiont 
can process. The symbiont reports the completion of each task to the job 
controller, but the symbiont contains no logic to determine that the print job 
as a whole is complete. 


In the processing of a print task, the symbiont performs three basic functions: 
input, format, and output. The symbiont performs these functions by calling 
routines to perform each function. 


The following steps describe the action taken by the symbiont in processing a 
task: 


1 The symbiont receives the print request from the job controller and stores 
it in a message buffer. 


2 The symbiont searches its list of input routines and selects the first input 
routine that is applicable to the print task. : 


3 The input routine returns a data record to the symbiont’s input buffer or 
in a buffer supplied by the input routine. 


4 Data in the input buffer is moved to the symbiont’s output buffer by the 
formatting routines, which format it in the process. 


5 Data in the output buffer is sent to the printing device by the output 
routine. 


6 When an input routine completes execution, that is, when it has no 


more input data to process, the symbiont selects another applicable input 
routine. Steps 3, 4, and 5 are repeated until all applicable input routines 
have executed. 


7 The symbiont informs the job controller that the task is complete. 


Figure 10-2 illustrates the steps taken by the symbiont in the processing of a 
print task. 
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Figure 10-2 Symbiont Execution Sequence or Flow of Control 
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As Figure 10-2 shows, most of the input routines execute in a specified 
sequence. This sequence is defined by the symbiont’s main control routine. 
You cannot modify this main control routine; thus, you cannot modify the 
sequence in which symbiont routines are called. 


The input routines that do not execute in sequence are called “demand input 
routines.” These routines are called whenever the service they provide is 
required and include the page header, page setup, and library module input 
routines. 


The symbiont can perform input, formatting, and output functions 
asynchronously; that is, the order in which the symbiont calls the input, 
formatting, and output routines can vary. For example, the symbiont can call 
an input routine, which returns a record to the input buffer; it can then call 
the format routine, which moves that record to the output buffer; and then 

it can call the output routine to move that data to the printing device. This 
sequence results in the movement of a single data record from disk to printing 
device. 


On the other hand, the symbiont can call the input and formatting routines 
several times before calling the output routine for a single buffer. The buffer 
can contain one or more formatted input records. In some cases an output 
buffer might contain only a portion of an input record. 


In this way the symbiont can buffer input records; then call the format 
routine, which moves one of those records to the output buffer; and finally 
call the output routine, which moves that data to the printing device. Note, 
however, that the formatting routine must be called once for each input 
record. 
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Similarly, the symbiont can buffer several formatted records before calling the 
output routine to move them to the printing device. 


The symbiont requires this flexibility in altering the sequence in which input, 
format, and output routines are called for reasons of efficiency (high rate of 
throughput) and adaptability to various system parameters and system events. 


The value specified with the call to PSM$PRINT determines the maximum 
size of the symbiont’s output buffer, which cannot be larger than the value 
of the SYSGEN parameter MAXBUF. If the buffer is very small, the symbiont 
might need to call its output routine one or more times for each record 
formatted. If the buffer is large, the symbiont will buffer several formatted 
records before calling the output routine to move them to the printing device. 





10.3. Symbiont Modification Procedure 


To modify the VMS print symbiont, perform the following steps. These steps 
are described in more detail in the sections that follow. 


1 Determine the modification needed. The modification might involve 
changing the way the symbiont performs a certain function, or it might 
involve adding a new function. 


2 Determine where to make the modification. This involves selecting 
a function and determining where that function is performed within 
the symbiont’s execution sequence. You specify a function by calling 
the PSM$REPLACE routine and specifying the code that identifies the 
function. 


Some codes correspond to symbiont-supplied routines. When you specify 
one of these codes, you replace that routine with your routine. Other 
codes do not correspond to symbiont-supplied routines. When you 
specify one of these codes, you add your routine to the set of routines the 
symbiont executes. Table 10-1 lists these codes. 


3 Write the routine. Because the symbiont calls your routine, your routine 
must have one of three call interfaces, depending on whether it is an 
input, format, or output routine. See the descriptions of the USER- 
INPUT-ROUTINE, USER-FORMAT-ROUTINE, and USER-OUTPUT- 
ROUTINE routines, which follow the descriptions of the PSM routines. 


4 Write the symbiont-initialization routine. This routine executes when 
the symbiont is first activated by the job controller. It initializes the 
symbiont’s internal database; specifies, by calling PSM$REPLACE, 
the routines you have supplied; activates the symbiont by calling 
PSM$PRINT; and performs any necessary cleanup operations when 
PSM$PRINT completes. 


5 Construct the modified symbiont. This involves compiling your routines, 
then linking them. 


6 Integrate the modified symbiont with the system. This involves placing 
the executable image in SYS$SYSTEM, identifying the symbiont image to 
the job controller, and debugging the symbiont. 
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As mentioned previously, you identify each routine you write for the 
symbiont by calling the PSM$REPLACE routine. The code argument for 
this routine specifies the point within the symbiont’s execution sequence 
at which you want your routine to execute. You should know which code 
you will use to identify your routine before you begin to write the routine. 
Section 10.3.6 provides more information about these codes. 


10.3.1 Guidelines and Restrictions 
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The following guidelines and restrictions apply to the writing of any symbiont | 
routine: 


¢ Do not use the process-permanent files identified by the logical names 
SYS$INPUT, SYS$OUTPUT, SYS$ERROR, and SYS$COMMAND. 


¢ Do not use the system services SYS$HIBER and SYS$WAKE. 


e Use the following two Run-Time-Library routines for allocation and 
deallocation of memory: LIB$}GET_VM and LIB$FREE_VM. 


¢ Minimize the amount of time that your routine spends executing at AST 
level. The job controller sends messages to the symbiont by means of 
user-mode ASTs; the symbiont cannot receive these ASTs while your user 
routine is executing at AST level. 


¢ The symbiont can call your routines at either AST level or non-AST level. 


e If your routine returns any error-condition value (low bit clear), the 
symbiont aborts the current task and notifies the job controller. Note 
that, by default, an error-condition value returned during the processing 
of a task causes the job controller to abort the entire job. However, this 
default behavior may be overridden. See the description of the /RETAIN 
qualifier of the DCL commands START/QUEUE, INITIALIZE/QUEUE, 
and SET QUEUE in the VMS DCL Dictionary. 


The symbiont stores the first error-condition value (low bit clear) returned 
during the processing of a task. The symbiont’s file-errors routine, an 
input routine (code PSM$K_FILE_ERRORS), places the message text 
associated with this condition value in the symbiont’s input stream. The 
symbiont prints this text at the end of the listing, immediately before the 
trailer pages. | 


The symbiont sends this error-condition value to the job controller; the 
job controller then stores this condition value with the job record in the 
job controller’s queue file. The job controller also writes this condition 

value in the accounting record for the job. 


If you choose to return a condition value when an error occurs, you 
should choose one from the system message file. This allows system 
programs to access the message text associated with the condition value. 
Specifically, the Accounting and SHOW/QUEUE utilities and the job 
controller will be able to translate the condition value to its corresponding 
message text and to display this message text as appropriate. 


This guideline applies to input, input-filter, and output-filter routines, and 
to the symbiont’s use of dynamic string descriptors in these routines. 


Print Symbiont Modification (PSM) Routines 
10.3 Symbiont Modification Procedure 


The simplest way for an input routine to pass the data record to the 
symbiont is for it to use an RTL string-handling routine (for example, 
STR$COPY_R). These routines use dynamic string descriptors to point to 
the record they have handled to copy the record from your input buffer 
to the symbiont-supplied buffer specified in the funcdesc argument to the 
input routine. 


By default, the symbiont initializes a dynamic string descriptor that your 
input routine can use to describe the data record it returns. Specifically, 
the symbiont initializes the DSC$B_DTYPE field of the string descriptor 
with the value DSC$K_DTYPE_T (which indicates that the data to 
which the descriptor points is a string of characters) and initializes the 
DSC$B_CLASS field with the value DSC$K_CLASS_D (which indicates 
that the descriptor is dynamic). 


Alternatively, the input routine can pass a data record to the symbiont 
by providing its own buffer and passing a static string descriptor that 
describes the buffer. To do this, you must redefine, using the following 
steps, the fields of the descriptor to which the funcdesc argument points: 


1 Initialize the field DSC$B_CLASS with the value 
DSC$K_CLASS_S (which indicates that the descriptor points to a 
scalar value or a fixed-length string). 


2 Initialize the field DSC$A_POINTER with the address of the buffer 
that contains the data record. 


3 Initialize the field DSC$W_LENGTH with the length, in bytes, of the 
data record. 


Each time the symbiont calls the routine to read some data, the symbiont 
reinitializes the descriptor to make it a dynamic descriptor. Consequently, 
if you want to use the descriptor as a static descriptor, your input routine 
must initialize the descriptor as described previously every time it is 
called to perform a reading operation. 


Input-filter routines and output-filter routines return a data record to 

the symbiont by means of the func_desc_2 argument. The symbiont 
initializes a descriptor for this argument the same way it does for 
descriptors used by input routine described previously. Thus, the 
guidelines described for the input routine apply to the input-filter routine 
and output-filter routine. 


10.3.2 Writing an Input Routine 


This section provides additional information to that given in Section 10.3 on 
writing an input routine. It provides an overview of the logic used in the 
VMS print symbiont’s main input routine, and it discusses the way in which 
the VMS print symbiont handles carriage-control effectors. 


The print symbiont calls your input routine, supplying it with arguments. 
Your routine must return arguments and condition values to the print 
symbiont. For this reason, your input routine must use the interface described 
in the description of the USER-INPUT-ROUTINE. 


When the print symbiont calls your routine, it specifies a particular request in 
the func argument. Each function has a corresponding code. 
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Your routine must provide the functions identified by the codes 
PSM$K_—OPEN, PSM$K_READ, and PSM$K—CLOSE. Your routine need 
not respond to the other function codes, but it can if you want it to. If your 
routine does not provide a function that the symbiont requests, it must return 
the condition value PSM$_FUNNOTSUP to the symbiont. 


The description of the func argument of the USER-INPUT-ROUTINE 
describes the codes that the symbiont can send to an input routine. 


See Section 10.3.5 for additional information about other function codes used 
in the user-written input routine. 


For each task that the symbiont processes, it calls some input routines only 
once, and some more than once; it always calls some routines, and calls 
others only when needed. 


Table 10-1 lists the codes that you can specify when you call the 
PSM$REPLACE routine to identify your input routine to the symbiont. 
The description of the PSM$REPLACE routine describes these routines. 


10.3.2.1 Internal Logic of the Symbiont’s Main Input Routine 
The internal logic of the symbiont’s main input routine, as described in this 
section, is subject to change without notice. This logic is summarized here. 
This summary is not intended as a tutorial on the writing of a symbiont’s 
main input routine, although it does provide insight into such a task. 


A main input routine is one that the symbiont calls to read data from the 
file that is to be printed. A main input routine must perform three sets of 
tasks: one set when the symbiont calls the routine with an OPEN request, 
one set when the symbiont calls with a READ request, and one set when the 
symbiont calls with a CLOSE request. 


The following table names the codes that identify each of these three requests 
and describes the tasks that the VMS symbiont’s main input routine performs 
for each of these requests. 


Code Action Taken by the Input Routine 
PSM$K_OPEN An OPEN request. When the main input routine receives this 


request code, it does the following: 
1. Opens the input file. 
2 Stores information about the input file. 


3 Returns the type of carriage control used in the input file. 
If this routine cannot open the file, it returns an error. 
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Code Action Taken by the Input Routine 


Note: The VMS print symbiont’s main input routine 
performs these tasks when it receives the 
PSM$K_START_TASK function code, rather than the 
PSM$K_OPEN function code. 


This atypical behavior occurs because some of the 
information stored by the main input routine must be 
available for other input routines that execute before 
the main input routine. For example, information 
about file attributes and record formats is needed by 
the symbiont’s separation-page routines, which print 
flag and burst pages. 


Consequently, if you supply your own main input 
routine, some of the information about the file being 
printed that appears on the standard separation pages 
is not available, and the symbiont prints a message on 
the separation page stating so. 


The symbiont receives the file-identification number from 
the job controller in the SMBMSG$K_FILE_IDENTIFICATION 
item of the requesting message and uses this value rather 
than the file specification to open the main input file. 


PSM$K_READ A READ request. When the main input routine receives this 
request, it returns the next record from the file. In addition, 
when the carriage control used by the data file is 
PSM$K_CC_PRINT, the main input routine returns the 
associated record header. 


PSM$K_CLOSE A CLOSE request. When the main input routine receives this 
request, it closes the input file. 


Symbiont Processing of Carriage Control 

Each input record can be thought of as consisting of three parts: leading 
carriage control, data, and trailing carriage control. Taken together, these 
three parts are called the composite data record. 


Leading and trailing carriage control are determined by the type of carriage 
control used in the file and explicit carriage-control information returned with 
each record. For embedded carriage control, however, leading and trailing 
carriage control is always null. 


The type of carriage control returned by the main input routine on the 
PSM$K_OPEN request code determines, for that invocation of the input 
routine, how the symbiont applies carriage control to each record that the 
main input routine returns on the PSM$K_READ request code. 


Note that, for all four carriage control types, the first character returned on 
the first PSM$K_READ call to an input routine receives special processing. If 
that character is a linefeed or a formfeed and if the symbiont is currently at 
line 1, column 1 of the current page, then the symbiont discards that linefeed 
or formfeed. 
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The Four Types of Carriage Control 


The following table briefly describes each type of carriage control and how 
the symbiont’s main input routine processes it. For a detailed explanation of 
each of these types of carriage control, refer to the description of the FAB$B_ 
RAT field of the FAB block in the VMS Record Management Services Manual. 


Type of Carriage Control 
Embedded 


FORTRAN 


PRN 


Implied 


10.3.3 Writing a Format Routine 


Symbiont Processing 


Leading and trailing carriage control are embedded 
in the data portion of the input record. Therefore, 
the symbiont supplies no special carriage control 
processing; it assumes that leading and trailing 
carriage control are null. 


The first byte of each data record contains 

a FORTRAN carriage-control character. This 
character specifies both the leading and trailing 
carriage control for the data record. The symbiont 
extracts the first byte of each data record and 
interprets that byte as a FORTRAN carriage- 
control character. If the data record is empty, the 
symbiont generates a leading carriage control of 
linefeed and a trailing carriage control of carriage 
return. 


Each data record contains a two-byte header that 
contains the carriage-control specifier. The first 
byte specifies the carriage control to apply before 
printing the data portion of the record. The second 
byte specifies the carriage control to apply after 
printing the data portion. The abbreviation PRN 
stands for print-file format. 


Unlike other types of carriage control, PRN carriage 
control information is returned through the funcarg 
argument of the main input routine; this occurs 
with the PSM$K_READ request. The funcarg 
argument specifies a longword; your routine writes 
the 2-byte PRN carriage control! specifier into the 
first two bytes of this longword. 


The symbiont provides a leading linefeed and 

a trailing carriage return. But if the data record 
consists of a single formfeed, the symbiont sets 
to null the leading and trailing carriage control for 
that record, and the leading carriage control for the 
record that follows it. 


To write a format routine, follow the modification procedure described in 
Section 10.3. Do not replace the VMS symbiont’s main format routine. 
Instead, modify its action by writing input and output filter routines. These 
execute immediately before and after the main format routine, respectively. 
The main formatting routine uses an undocumented and nonpublic interface; 
you cannot replace the main formatting routine. The DCL command PRINT 
/PASSALL bypasses the main format routine of the print symbiont. 


PSM-12 


Print Symbiont Modification (PSM) Routines 
10.3 Symbiont Modification Procedure 


See Section 10.3.5 for additional information about other function codes used 
in the user-written formatting routine. 


10.3.3.1 Internal Logic of the Symbiont’s Main Format Routine 
The main format routine contains all the logic necessary to convert composite 
data records to a data stream for output. Actions taken by the format routine 
include the following: 


e Tracking the current column and line 


¢ Implementing the special processing of the first character of the first 
record 


¢ Implementing the alignment data mask specified by the DCL command 
START /QUEUE/ALIGN=MASK 


e Handling margins as specified by the forms definition 


e Initiating processing of page headers when specified by the DCL 
command PRINT/HEADER 


e Expanding leading and trailing carriage control 

e Handling line overflow 

e Handling page overflow 

¢ Expanding tab characters to spaces for some devices 
e Handling escape sequences 

e Accumulating accounting information 


e Implementing double-spacing when specified by the DCL command 
PRINT /SPACE 


e Implementing automatic page ejection when specified by the DCL 
command PRINT/FEED 


The symbiont’s main format routine uses a special rule when processing 

the first character of the first composite data record returned by an input 
routine. (A composite data record is the input data record and a longword 
that contains carriage-control information for the input data record.) This rule 
is that if the first character is a vertical format effector (formfeed or linefeed) 
and if the symbiont has processed no printable characters on the current page 
(that is, the current position is column 1, line 1), then that vertical format 
effector is discarded. 


10.3.4 Writing an Output Routine 


To write an output routine, follow the modification procedure described in 
Section 10.3. 


The print symbiont calls your output routine. Input arguments are supplied 
by the print symbiont; output arguments and status values are returned by 
your routine to the print symbiont. For this reason, your output routine must 
have the call interface that is described in the USER-OUTPUT-ROUTINE 
routine. 


When the print symbiont calls your routine, it specifies in one of the input 
arguments—the func argument—the reason for the call. Each reason has a 
corresponding function code. 
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10.3.4.1 


There are several function codes that the print symbiont can supply when 
it calls your output routine. Your routine must contain the logic to respond 
to the following function codes: PSM$K—OPEN, PSM$K_WRITE, PSM$K_ 
WRITE_NOFORMAT, and PSM$K_CLOSE. 


It is not required that your output routine contain the logic to respond to the 
other function codes, but you can provide this logic if you want to. 


A complete list and description of all relevant function codes for output 
routines is provided in the description of the func argument of the USER- 
OUTPUT-ROUTINE routine. 


See Section 10.3.5 for additional information about other function codes. 


Internal Logic of the Symbiont’s Main Output Routine 
When the symbiont calls the main output routine with the PSM$K_OPEN 
function code, the main output routine takes the following steps: 


1 Allocates the print device 

2 Assigns a channel to the device 
3 Obtains the device characteristics 
4 


Returns the device-status longword in the funcarg argument (for more 
information, see the description of the SMBMSG$K_DEVICE_STATUS 
message item in Section 10, Symbiont/Job-Controller Interface (SMB) 
Routines) 


5 Returns an error if the device is not a terminal or a printer 


When this routine receives a PSM$K_WRITE service request code, it sends 
the contents of the symbiont output buffer to the device for printing. 


When this routine receives a PSM$K_WRITE_NOFORMAT service request 
code, it sends the contents of the symbiont output buffer to the device for 
printing and suppresses device drive formatting as appropriate for the device 
in use. 


When this routine receives a PSM$K_CANCEL service request code, it 
requests the device driver to cancel any outstanding output operations. 


When this routine receives a PSM$K_CLOSE service request code, it 
deassigns the channel to the device and deallocates the device. 


10.3.5 Other Function Codes 
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notifies user-written input, output, and format routines using the following 
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Print Symbiont Modification (PSM) Routines 
10.3 Symbiont Modification Procedure 


Function Code Description 


PSM$K_START_STREAM Job controller sends a message to the symbiont to 
start a queue 


PSM$K_START_TASK Symbiont parses a message from job controller 
_ directing it to start a queue 
PSM$K_PAUSE_TASK Job controller sends a message to the symbiont to 


suspend processing of the current task 


PSM$K_STOP_STREAM Job controller sends a message to the symbiont to 
stop the queue 


PSM$K_STOP_TASK Job controller sends a message to the symbiont to 
stop the task 


PSM$K_RESUME_TASK Job controller sends a message to the symbiont to 
resume processing of the current task 


PSM$K_RESET_STREAM Same as PSM$K_STOP_STREAM 


10.3.6 Writing a Symbiont Initialization Routine 


Writing a symbiont initialization routine involves writing a program that calls 
the following: 


1 PSM$REPLACE once for each routine (input, output, or format) that you 
have written. PSM$REPLACE identifies your routines to the symbiont. | 


2 PSM$PRINT exactly once after you have identified all your service | 
routines using PSM$REPLACE. 


Table 10-1 lists all routine codes that you can specify in the PSM$REPLACE 
routine. Choosing the correct routine code for your routine is important 
because the routine code specifies when the symbiont will call your routine. 
The functions of these routines are described further in the description of the 
PSM$REPLACE routine. 


Column one in Table 10-1 lists each routine code. 


For those input routines that execute in a predefined sequence, the second 
column contains a number showing the order in which that input routine is 
called relative to the other input routines for a single file job. If the routine 
does not execute in a predefined sequence, the second column contains the 
character x. 


Column three specifies whether the routine is an input, format, or output 
routine; this information directs you to the section describing how to write a 
routine of that type. 


Column four specifies whether there is a symbiont-supplied routine 
corresponding to that routine code. The codes for the input-filter and output- 
filter routines, which have no corresponding routines in the VMS symbiont, 
allow you to specify new routines for inclusion in the symbiont. 
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Table 10—1 Routine Codes for Specification to PSM$REPLACE 


Routine Code Sequence Function Supplied 
PSM$K_JOB_SETUP 1 Input Yes 
PSM$K_FORM_SETUP 2 Input Yes 
PSM$K_JOB._FLAG 3 Input Yes 
PSM$K_JOB_BURST 4 Input Yes 
PSM$K_FILE_SETUP 2 Input Yes 
PSM$K_FILE_FLAG 6 Input Yes 
PSM$K_FILE_BURST 7 Input Yes 
PSM$K_FILE_SETUP_2 8 Input Yes 
PSM$K_MAIN_INPUT 9 Input Yes 
PSM$K_FILE_INFORMATION 10 Input Yes 
PSM$K_FILE_ERRORS 11 Input Yes 
PSM$K_FILE_TRAILER 12 Input Yes 
PSM$K_JOB_RESET 13 Input Yes 
PSM$K_JOB_TRAILER 14 Input Yes 
PSM$K_JOB_COMPLETION 15 Input Yes 
PSM$K__PAGE_SETUP x Input Yes 
PSM$K_PAGE_HEADER X Input Yes 
PSM$K__LIBRARY_INPUT x Input Yes 
PSM$K_INPUT_FILTER x Formatting No 
PSM$K_MAIN_ FORMAT x Formatting Yes 
PSM$K__OUTPUT_FILTER x Formatting No 
PSM$K_OUTPUT x Output Yes 


10.3.7 Integrating a Modified Symbiont 


To integrate your user routine and the symbiont initialization routine, perform 
the following steps; note that the sequence of steps described here assumes 
that you will be debugging the modified symbiont: 


1 Compile or assemble the user routine and the symbiont initialization 
routine into an object module. 


2 Enter the following DCL command: 
$ LINK/DEBUG your-symbiont 


The file name your-symbiont is the object module built in step 1. Symbols 
necessary for this link operation are located in the shareable images 
SYS$SHARE:SMBSRVSHR.EXE and SYS$LIBRARY:IMAGELIB.EXE. The 
linker automatically searches these shareable images and extracts the 
necessary information. 


3 Place the resulting executable symbiont image in SYS$SYSTEM. 
4 Locate two unallocated terminals: one at which to issue DCL commands 


and one at which to debug the symbiont image. 
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5 Log in on one of the terminals under UIC [1,4], which is the system 
manager’s account. This terminal is the one at which you enter DCL 
commands. Do not log in at the other terminal. 


6 Enter the following DCL command: 
$ SET TERMINAL/NODISCONNECT/PERMANENT _TTcu: 


The variable _TTcu: is the physical terminal name of the terminal at 
which you want to debug (the terminal you are not logged in at). The 
underscore (_) and colon (:) characters must be specified. 


7 ‘Enter the following DCL commands: 


$ DEFINE/GROUP DBG$INPUT _TTcu: 
$ DEFINE/GROUP DBG$OUTPUT _TTcu: 


The variable _TTcu: specifies the physical terminal name of the terminal 
at which you will be debugging. Note that other users having a UIC with 
group number 1 should not use the debugger at the same time. 


8 Initialize the queue by entering the following DCL command: 
$ INITIALIZE/QUEUE/PROCESSOR= your-symbiont /ON= printer_name 


The symbiont image specified by the file name your-symbiont must 
reside in SYS$SYSTEM. Note too that the /PROCESSOR qualifier 
accepts only a file name; the device, directory, and file type default to 
SYS$SYSTEM:.EXE. 


The /ON qualifier specifies the device that will be served by the symbiont 
while you debug the symbiont. 


9 Enter the following DCL command to execute the modified symbiont 
routine: 


$ PRINT/HEADER/QUEUE=queue-id 


Enter the following DCL command to start the queue and invoke the 
debugger: 


$ START/QUEUE queue-name 


10 After you debug your symbiont, relink the symbiont by entering the 
following DCL command: 


$ LINK/NOTRACEBACK/NODEBUG your-symbiont 


11 Deassign the logical names DBG$INPUT and DBG$OUTPUT so that they 
will not interfere with other users in UIC group 1. 





10.4 Example of Using the PSM Routines 


Example 10-1 shows how to use PSM routines to supply a page header 
routine in a MACRO program. 
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Example 10—1 Using PSM Routines to Supply a Page Header Routine in a MACRO 
Program 





.TITLE EXAMPLE - Example user modified symbiont 
.IDENT 'V03-000' 


; THIS PROGRAM SUPPLIES A USER WRITTEN PAGE HEADER 

: ROUTINE TO THE STANDARD SYMBIONT. THE PAGE HEADER 

; INCLUDES THE SUBMITTER'S ACCOUNT NAME AND USER NAME, 
; THE FULL FILE SPECIFICATION, AND THE PAGE NUMBER. 

; THE HEADER LINE IS UNDERLINED BY A ROW OF DASHES 

: PRINTED ON A SECOND HEADER LINE. 


; System definitions 


$PSMDEF ; Symbiont definitions 
$SMBDEF ; Message item definitions 
$DSCDEF ; Descriptor definitions 


; Define argument offsets for user supplied services called by symbiont 


CONTEXT = 04 ; Symbiont context 

WORK_AREA = 08 ; user context 

FUNC = 12 ; function code 

FUNC_DESC = 16 ; function dependent descriptor 
FUNC_ARG = 20 ; function dependent argument 


; Macro to create dynamic descriptors 


.MACRO D_DESC 


-WORD O ; DSC$W_LENGTH = 0 
.BYTE DSC$K_DTYPE_T ; DSC$B_DTYPE = STRING 
.BYTE DSC$K_CLASS_D ; DSC$B_CLASS = DYNAMIC 
-LONG 0 ; DSC$A_POINTER = 0 
. ENDM 
; Storage for page header information 
FILE: D_DESC ; file name descriptor 
USER : D_DESC ; user name descriptor 
ACCOUNT: D_DESC ; account name descriptor 
PAGE: .LONG 0O ; page number 
LINE: .LONG 0 ; line number 
; FAO control string and work buffer. Header format: 
; "[account,name] filename ........ Page 9999" 
FAO_CTRL: -ASCID /!71<[!AS, !AS] !AS!>Page 9999/ 
FAO_CTRL_2: - .ASCID /!4UL/ 
FAO_DESC: .LONG 80 ; work buffer descriptor 
-ADDRESS FAO_BUFF 


FAO_BUFF: . BLKB 80 ; work buffer 





Example 10—1 Cont'd. on next page 
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Example 10—1 (Cont.) Using PSM Routines to Supply a Page Header Routine ina MACRO 
Program 





; Own storage for values passed by reference 


CODE: .LONG 0 ; service or item code 
STREAMS : .LONG i ; number of simultaneous streams 
BUFSIZ: .LONG 2048 ; output buffer size 
LINSIZ: .WORD 81 ; line size for underlines 
; Main routine -- invoked at image startup 
START: .WORD 0 ; save nothing because this routine uses only RO and Ri 


; Supply private page header routine 


MOVZBL #PSM$K_PAGE_HEADER , CODE ; set the service code 

PUSHAL HEADER ; address of modified routine 
PUSHAL CODE ; address of service code 
CALLS #2,G°PSM$REPLACE ; replace the routine 

BLBC RO, 10$ ; exit if any errors 


; Transfer control to the standard symbiont 


PUSHAL BUFSIZ ; address of output buffer size 
PUSHAL STREAMS ; address of number of streams 
CALLS #2,G°PSM$PRINT ; invoke standard symbiont 

10$: RET 


; Page header routine 


HEADER: .WORD 0O ; Save nothing 


; Check function code 


CMPL #PSM$K_START_TASK , @FUNC (AP) ; new task? 
BEQL 20$ ; branch if so 
CMPL #PSM$K_READ , @FUNC (AP) ; READ function? 
BNEQ 15$ 
BEQL 50$ ; branch if so 
15$: CMPL #PSM$K_OPEN, @FUNC (AP) ; OPEN function? 
BNEQ 16$ 
BEQL 66$ ; branch if so 
16$: MOVL #PSM$_FUNNOTSUP , RO ; unsupported function 
RET ; return to symbiont 


a 


; Starting a new file 
20$: 


CLRL PAGE ; reset the page number 
MOVZBL #2,LINE ; and the line number 





Example 10-1 Cont'd. on next page 
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Example 10—1 (Cont.) 
Program 


; Get the account name 


MOVZBL 
PUSHAL 
PUSHAL 
PUSHAL 
CALLS 
BLBC 


#SMBMSG$K_ACCOUNT_NAME , CODE 
ACCOUNT 

CODE 

@CONTEXT (AP) 

#3 ,G°PSM$READ_ITEM_DX 

RO, 40$ 


; Get the file name 


MOVZBL 
PUSHAL 
PUSHAL 
PUSHAL - 
CALLS 
BLBC 


FILE 

CODE 

@CONTEXT (AP) 

#3 ,G*PSM$READ_ITEM_DX 
RO, 40$ 


; Get the user name 


MOVZBL 
PUSHAL 
PUSHAL 
PUSHAL 
CALLS 
BLBC 


#SMBMSG$K_USER_NAME , CODE 
USER 

CODE 

Q@CONTEXT (AP) 

#3, G°PSM$READ_ITEM_DX 
RO, 40$ 


#SMBMSG$K_F ILE_SPECIFICATION , CODE 


Using PSM Routines to Supply a Page Header Routine in a MACRO 


set item code 

address of descriptor 
address of item code 

address of symbiont ctx value 
read it 

branch if any errors 


; set item code 
address of descriptor 
address of item code 
address of symbiont ctx value 
read it 
branch if any errors 


set item code 

address of descriptor 
address of item code 

address of symbiont ctx value 
read it 

branch if any errors 


; Set up the static header information that is constant for the task 


$FAO_S CTRSTR = FAO_CTRL, - 
OUTBUF = FAO_DESC, - 
P1 = #ACCOUNT, - 
P2 = #USER, - 
P3 = #FILE 


40$: RET 


; Read a page header 


50$: 
DECL LINE 
BEQL 60$ 
BLSS 70$ 


; Insert the page number into the header 


INCL PAGE 

MOVAB = FAO_BUFF+76,FAO_DESC+4 

$FAO_S CTRSTR = FAO_CTRL_2, - 
OUTBUF = FAO_DESC, - 
Pi = PAGE 

MOVAB FAO_BUFF,FAO_DESC+4 

BLBC RO, 55$ 


Example 10-1 Cont'd. on next page 
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os 


we we we we 


we 


FAO control string desc 
output buffer descriptor 
account name descriptor 
user name descriptor 

file name descriptor 
return success or any error 


decrement the line number 
branch if second read 
branch if third read 


increment the page number 
point to page number buffer 
FAO control string desc 
output buffer descriptor 
page number 

point to work buffer 

return if error 
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10.4 Example of Using the PSM Routines 


Example 10—1 (Cont.) Using PSM Routines to Supply a Page Header Routine ina MACRO 


Program 





; Copy the line to the symbiont's buffer 


PUSHAB FAO_DESC 

PUSHL FUNC_DESC(AP) 

CALLS #2,G°STR$COPY_DX 
55$: RET 


; Second line -- underline header 


60$: 
PUSHL FUNC_DESC (AP) 
PUSHAL LINSIZ 
CALLS #2,G°STR$GET1_DX 
BLBC RO, 67$ 
MOVL FUNC_DESC (AP) ,R1 
MOVL A(R1i) ,R1 
MOVAB 80(R1i) ,RO 
65$: MOVB #°A/-/,(R1)+ 
CMPL RO,R1 
BGTRU 65$ 
MOVB #10, (R1)+ 
66$: MOVZBL #SS$_NORMAL, RO 
67$: RET 


; Done with this page header 
70$: 
MOVL #PSM$_EOF , RO 


MOVZBL #2,LINE 
RET 


.END =. START 


; work buffer descriptor 

; symbiont descriptor 

; copy to symbiont buffer 

; return success or any error 


; symbiont descriptor 

; number of bytes to reserve 
; reserve the space 

; exit if error 

; get address of descriptor 
; get address of buffer 

; set up transfer limit 

; fill with dashes 

; reached limit? 

; branch if not 

; extra line feed 

; set success 

; return 


; return end of input 
; reset line counter 
; return 





PSM Routines 


The following pages describe the individual PSM routines. 
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PSM$PRINT Invoke VMS-Supplied Print 
Symbiont 


The PSM$PRINT routine invokes the VMS-supplied print symbiont. 


PSM$PRINT must be called exactly once after all user service routines 
have been specified using PSM$REPLACE. 








FORMAT PSMS$PRINT [streams] [, bufsiz] [, worksiz] 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS streams 
VMS usage: longword_unsigned 
type: longword (unsigned) 
access: ‘read only 
mechanism: by reference 


Maximum number of streams that the print symbiont is to support. The 
streams argument is the address of a longword containing this number, 
which must be in the range 1 to 16. If you do not specify streams, a default 
value of 1 is used. Thus, by default, a user-modified print symbiont supports 
one stream, which is to say that it is a single-threaded symbiont. 


A stream (or thread) is a logical link between a print execution queue 
and a printing device. When a symbiont process can accept simultaneous 
links to more than one queue, that is, when it can service multiple queues 
simultaneously, the symbiont is said to be multithreaded. 


bufsiz 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Maximum buffer size in bytes that the print symbiont is to use for output 
operations. The bufsiz argument is the address of a longword containing the 
specified number of bytes. 


The print symbiont actually uses a buffer size that is the smaller of (1) the 
value specified by bufsiz or (2) the SYSGEN parameter MAXBUF. If you do 
not specify bufsiz, then the print symbiont uses the value of MAXBUF. 
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The print symbiont uses this size limit only for output operations. Output 
operations involve the placing of processed or formatted pages into a buffer 
that will be passed to the output routine. 


The print symbiont uses the value specified by bufsiz only as an upper limit; 
most buffers that it writes will be smaller than this value. 


worksiz 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Size in bytes of a work area to be allocated for the use of user routines. The 
worksiz argument is the address of a longword containing this size in bytes. 
If you do not specify worksiz, no work area is allocated. 


A separate area of the specified size is allocated for each active symbiont 
stream. 





DESCRIPTION 


The PSM$PRINT routine must be called exactly once after all user routines 
have been specified to the print symbiont. Each user routine is specified to 
the symbiont in a call to the PSM$REPLACE routine. 


The PSM$PRINT routine allows you to specify whether the print symbiont 
is to be single-threaded or multithreaded, and if multithreaded, how many 
streams or threads it can have. In addition, this routine allows you to control 
the maximum size of the output buffer. 





CONDITION 
VALUES 
RETURNED 


SS$_NORMAL Normal successful completion. 


This routine also returns any condition values returned by the $SETPRV, 
$GETSYI, $PURGWS, and $DCLAST system services, as well as any 
condition values returned by the SMB$INITIALIZE routine documented 
in Chapter 11. 
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PSMS$READ_ITEM_DX Obtain Value of Message 


Items 


The PSM$READ_ITEM_DxX routine obtains the value of message items 
that are sent by the job controller and stored by the VMS symbiont. 











FORMAT PSMS$READ_ITEM_DX _request_id ,item ,buffer 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS _ request_id 
VMS usage: address 
type: longword (unsigned) 
access: read only 
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mechanism: by reference 


Request identifier supplied by the symbiont to the user routine currently 
calling PSM$READ_ITEM—DxX. The symbiont always supplies a request 
identifier when it calls a user routine with a service request. The request_id 
argument is the address of a longword containing this request identifier value. 


Your user routine must copy the request identifier value that the symbiont 
supplies (in the request—id argument) when it calls your user routine. Then, 
when your user routine calls PSM$READ_ITEM_Dx, it must supply (in 

the request_id argument) the address of the request identifier value that it 
copied. 


item 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 


mechanism: by reference 


Item code that identifies the message item that PPM$READ_ITEM_DxX is to 
return. The item argument is the address of a longword that specifies the 
item’s code. 


For a complete list and description of each item code, refer to the 
documentation of the item argument in the SMBSREAD_MESSAGE_ITEM 
routine in Chapter 11. 
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buffer 

VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor 


Buffer into which PSM$READ_ITEM_DxX returns the specified informational 
item. The buffer argument is the address of a descriptor pointing to this 
buffer. 


The PSM$READ_ITEM_DxX routine returns the specified informational item 
by copying that item to the buffer using one of the STR6COPY_xx routines 
documented in the VMS Run-Time Library Routines Volume. 





DESCRIPTION 


The PSM$READ_ITEM_DxX routine obtains the value of message items that 
are sent by the job controller and stored by the VMS symbiont. You use 
PSM$READ_ITEM_DxX to obtain information about the task currently being 
processed, for example, the name of the file being printed (GMBMSG$K_ 
FILE_SPECIFICATION) or the name of the user who submitted the job 
(SMBMSG$K_USER_NAME). 





CONDITION 
VALUES 
RETURNED 


SS$_NORMAL Normal successful completion. 
PSM$_INVITMCOD Invalid item code specified in the item argument. 


This routine also returns any condition values returned by any of the 


STR$COPY_xx routines documented in the VMS Run-Time Library Routines 
Volume. 
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PSMS$REPLACE Declare User Service Routine 


The PSM$REPLACE routine substitutes a user service routine for a 
symbiont routine or adds a user service routine to the set of symbiont 








routines. 
You must call PSM$REPLACE once for each routine that you replace or 
add. 
FORMAT PSMS$REPLACE code ,routine 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. The condition value that this routine can return is listed under 
CONDITION VALUE RETURNED. 





ARGUMENTS ~— code 
VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Routine code that identifies the symbiont routine to be replaced by a user 
service routine. The code argument is the address of a longword containing 
the routine code. 


Some routine codes identify routines that are supplied with the VMS 
symbiont; when you specify such a routine code, you replace the symbiont- 
supplied routine with your service routine. 


Two routine codes identify routines that are not supplied with the VMS 
symbiont; when you specify such a routine code, your service routine is 
added to the set of symbiont routines. 


Table 10-1 lists each routine code in the order in which it is called within the 
symbiont execution stream; this table also specifies whether a routine code 
identifies an input, formatting, or output routine, and whether the routine is 
supplied with the VMS symbiont. 


The routine codes are defined by the $PSMDEF macro. The following pages 
list each routine code in alphabetical order; the description of each code 
includes the following information about its corresponding routine: 


e Whether the routine is supplied by the VMS symbiont 


e Whether the routine is an input, formatting, or output routine 
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e Under what conditions the routine is called 


e¢ What task the routine performs 


Routine Codes 


PSM$K_FILE_BURST 


This code identifies a symbiont-supplied input routine; it is called whenever 

a file burst page is requested. This routine obtains information about the job, 
formats the file burst page, and returns the contents of the page to the input 
buffer. A file burst page follows a file flag page and precedes the contents of 
the file. 


PSMS$K_FILE_ERRORS 


This code identifies a symbiont-supplied input routine; it is called when errors 
have occurred during the job. This routine places the error message text in 
the input buffer. 


PSM$K_FILE_FLAG 


This code identifies a symbiont-supplied input routine; it is called whenever 
a file flag page is requested. This routine obtains information about the job, 
formats the file flag page, and returns the contents of the page to the input 
buffer. A flag page follows the job burst page (if any) and precedes the file 
burst page (if any). It contains such information as the file specification of the 
file and the name of the user issuing the print request. 


PSM$K_FILE_INFORMATION 

This code identifies a symbiont-supplied input routine; it is called when the 
file information item has been specified by the job controller. This routine 
expands the file information item to text and returns it to the input buffer. 


PSM$K_FILE_SETUP 

This code identifies a symbiont-supplied input routine; it is always called. 
This routine queues any specified file-setup modules for insertion in the input 
stream when the PSM$K_FILE_SETUP routine closes. 


PSM$K_FILE_SETUP_2 

This code identifies a symbiont-supplied input routine; it is always called. 
This routine returns a formfeed to ensure that printing of the file begins at the 
top of the page. This routine is called just before the main input routine. 


PSMS$K_FILE_TRAILER 

This code identifies a symbiont-supplied input routine; it is called whenever a 
file trailer page is requested. This routine obtains information about the job, 
formats the file trailer page, and returns the contents of the page to the input 
buffer. A trailer page follows the last page of the file contents. 


PSM$K_MAIN_FORMAT 


This code identifies the symbiont-supplied formatting routine; it is always 
called. This routine performs numerous formatting functions. You cannot 
replace this routine. 


PSM$K_FORM_SETUP 


This code identifies a symbiont-supplied input routine; it is always called. 
This routine queues any specified form-setup modules for insertion in the 
input stream when the PSM$K_FORM_SETUP routine closes. 
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PSM$K_INPUT_FILTER 


This code identifies a format routine that is not supplied by the VMS 
symbiont. If the routine is supplied by the user, it is always called 
immediately prior to the symbiont-supplied formatting routine (routine 
code PSM$K_MAIN_FORMAT). An input-filter service routine is useful 
for modifying input data records and their carriage control before they are 
formatted by the symbiont. 


PSM$K_JOB_BURST 


This code identifies a symbiont-supplied input routine; it is called whenever 
a job burst page is requested. This routine obtains information about the job, 
formats the job burst page, and returns the contents of the page to the input 
buffer. A job burst page follows the job flag page and precedes the file flag 
page (if any) of the first file in the job. It is similar to a file burst page except 
that it appears only once per job and only at the beginning of the job. 


PSM$K_JOB_COMPLETION 


This code identifies a symbiont-supplied input routine; it is always called. 
This routine returns a formfeed, which causes any output buffered by the 
device to be printed. 


PSM$K_JOB_FLAG 


This code identifies a symbiont-supplied input routine; it is called whenever 
a job flag page is requested. This routine obtains information about the job, 
formats the job flag page, and returns the contents of the page to the input 
buffer. A job flag page is similar to a file flag page except that it appears only 
once per job, preceding the job burst page (if any). 


PSMS$K_JOB_RESET 


This code identifies a symbiont-supplied input routine; it is always called. 
This routine queues any specified job-reset modules for insertion in the input 
stream when the PSM$K_JOB_RESET routine closes. 


PSM$K_JOB_SETUP 


This code identifies a symbiont-supplied input routine; it is always called. 
This routine checks to see if this is the first job to be printed on the device, 
and if so, it issues a formfeed and then performs a job reset. See the 
description of the PSM$K_JOB_RESET routine for information about job 
reset. 


PSM$K_JOB_TRAILER 


This code identifies a symbiont-supplied input routine; it is called whenever a 
job trailer page is requested. This routine obtains information about the job, 
formats the job trailer page, and returns the contents of the page to the input 
buffer. A job trailer page is similar to a file trailer page except that it appears 
only once per job, as the last page in the job. 


PSM$K_MAIN_INPUT 


This code identifies a symbiont-supplied input routine; it is always called. 
This routine opens the file to be printed, returns input records to the input 
buffer, and closes the file. 
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PSM$K_LIBRARY_INPUT 


This code identifies a symbiont-supplied input routine; it is called when an 
input routine closes and when modules have been requested for insertion in 
the input stream. This routine returns the contents of the specified modules, 
one record per call. You cannot replace this routine. 


PSM$K_OUTPUT_FILTER 


This code identifies a formatting routine that is not supplied by the VMS 
symbiont. If the routine is supplied by the user, it is always called. This 
routine executes prior to the symbiont output routine (routine code 
PSM$K_OUTPUT). An output-filter service routine is useful for modifying 
output data buffers before they are passed to the output routine. 


At the point where the output-filter routine executes within the symbiont 
execution stream, the input data is no longer in record format; instead, the 
data exists as a stream of characters. The carriage control, for example, is 
embedded in the data stream. Thus, the output buffer may contain what was 
once a complete record, part of a record, or several records. 


PSM$K_PAGE_HEADER 


This code identifies a symbiont-supplied input routine; it is called once at the 
beginning of each page if page headers are requested. This routine returns to 
the input buffer one or more lines containing information about the file being 
printed and the current page number. This routine is called only while the 
main input routine is open. 


PSM$K_PAGE_SETUP 


This code identifies a symbiont-supplied routine; it is called at the beginning 
of each page if page-setup modules were specified. This routine queues any 
specified page-setup modules for insertion in the input stream when the 
PSM$K_PAGE_SETUP routine closes. This routine is called only while the 
main input routine is open. 


PSM$K_OUTPUT 

This code identifies the symbiont-supplied output routine; it is always called. 
This routine writes the contents of the output buffer to the printing BEVACE, 
but it also performs many other functions. 


routine 

VMS usage: procedure 

type: procedure entry mask 
access: read only 


mechanism: by reference 


User service routine that is to replace a symbiont routine or to be included. 
The routine argument is the address of the user routine entry point. 





DESCRIPTION 


The PSM$REPLACE routine must be called each time a user service routine 
replaces a symbiont routine or is added to a set of symbiont routines. 


The code argument specifies the symbiont routine to be replaced. The routine 
codes that can be specified in the code argument are of two types: those 
that identify existing print symbiont routines and those that do not. All the 
routine codes are similar, however, in the sense that each supplies a location 
within the print symbiont execution stream where your routine can execute. 
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By selecting a routine code that identifies an existing symbiont routine, you 
effectively disable that symbiont routine. The service routine that you specify 
may or may not perform the function that the disabled symbiont routine 
performs. If it does not, the net effect of the replacement is to eliminate that 
function from the list of functions performed by the print symbiont. Exactly 
what your service routine does is up to you. 


By selecting a routine code that does not identify an existing symbiont routine 
(those that identify the input-filter and output-filter routines), your service 
routine has a chance to execute at the location signified by the routine code. 
Because the service routine you specify to execute at this location does not 
replace another symbiont routine, your service routine is an addition to the 
set of symbiont routines. 


As mentioned, each routine code identifies a location in the symbiont 
execution stream, whether or not it identifies a symbiont routine. Table 10-1 
lists each routine code in the order in which the location it identifies is 
reached within the symbiont execution stream. 





CONDITION | 
VALUE SS$_NORMAL Normal successful completion. 


RETURNED 
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PSM$REPORT Report Completion Status 


The PSM$REPORT routine reports to the print symbiont the completion 
status of an asynchronous operation initiated by a user routine. 


Such a user routine must return the completion status PSM$_PENDING. 
PSM$REPORT must be called exactly once for each time a user routine 
returns the status PSM$_PENDING. 








FORMAT PSM$REPORT _request_id [, status] 
RETURNS VMS usage: .cond_value 

type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. The condition value that this routine can return is listed under 
CONDITION VALUE RETURNED. 





ARGUMENTS request_id 
VMS usage: identifier 
type: longword (unsigned) - 
access: read only 
mechanism: by reference 


Request identifier supplied by the symbiont to the user routine at the time 
the symbiont called the user routine with the service request. The user 
routine must return the completion status PSM$_PENDING on the call for 
this service request. The request_id argument is the address of a longword 
containing the request identifier value. 


The symbiont calls the user routine with a request code that specifies the 
function that the symbiont expects the user routine to perform. In the call, 
the symbiont also supplies a request identifier, which serves to identify the 
request. If the user routine initiates an asynchronous operation, a mechanism 
is required for notifying the symbiont that the asynchronous operation has 
completed and for providing the completion status of the operation. 


The PSM$REPORT routine conveys the above two pieces of information. 

In addition, PSM$REPORT returns to the symbiont (in the request_id 
argument) the same request identifier value as that supplied by the symbiont 
to the user routine that initiated the operation. In this way, the symbiont 
synchronizes the completion status of an asynchronous operation with that 
invocation of the user routine that initiated the operation. 


Any user routine that initiates an asynchronous operation must, therefore, 
copy the request identifier value that the symbiont supplies (in the 
request_id argument) when it calls the user routine. The user routine will 
later need to supply this value to PSM$REPORT. 
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In addition, when the user routine returns, which it does before the 
asynchronous operation has completed, the user routine must return the 
status PSM$_PENDING. 


status 

VMS usage: cond_value 

type: longword (unsigned) 
access: write only 


mechanism: by reference 


Completion status of the asynchronous operation that has completed. The 
status argument is the address of a longword containing this completion 
status. The status argument is optional; if it is not specified, the symbiont 
assumes the completion status SS$_NORMAL. 


The user routine that initiates the asynchronous operation must test 
for the completion of the operation and must supply the operation’s 
completion status as the status argument to the PSM$REPORT routine. 
The DESCRIPTION section describes this procedure in greater detail. 


If the completion status specified by status has the low bit clear, the symbiont 
aborts the task. 





DESCRIPTION = Anasynchronous operation is an operation that, once initiated, executes “off 
to the side” and need not be completed before other operations can begin 
to execute. Asynchronous operations are common in symbiont applications 
because a symbiont, if it is multithreaded, must handle concurrent I/O 
operations. 


One example of a user routine that performs an asynchronous operation is 
an output routine that calls the $QIO system service to write a record to the 
printing device. When the user output routine completes execution, the I/O 
request queued by $QIO may not have completed. In order to synchronize 
this I/O request, that is, to associate the I/O request with the service request 
that initiated it, you should use the following mechanism: 


1. In making the call to $QIO, specify the astadr and iosb arguments. The 
astadr argument specifies an AST routine to execute when the queued 
output request has completed, and the iosb argument specifies an I/O 
status block to receive the completion status of the I/O operation. Item 3 
describes some functions that your AST routine will need to do. 


2 Have the user output routine return the status PSM$_PENDING. 
3 Write the AST routine to perform the following functions: 


a. Copy the completion status word from the I/O status block to a 
longword location that you will specify as the status argument in the 
call to PSM$REPORT. 


b. Call PSM$REPORT. Specify as the request_id argument the request 
identifier that was supplied by the print symbiont in the original call 
to the user output routine. 





CONDITION | 
VALUE SS$_NORMAL Normal successful completion. 


RETURNED 
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USER-FORMAT-ROUTINE Invoke User-Written 


Format Routine 


The user-written USER-FORMAT-ROUTINE performs format operations. 
The symbiont’s control logic routine calls your format routine at one of 
two possible points within the symbiont’s execution stream. You select 
this point by specifying one of two routine codes when you call the 
PSM$REPLACE routine. 


A user format routine may be an input filter routine (routine code 
PSM$K_INPUT_FILTER) or an output filter routine (routine code 
PSM$K_OUTPUT_FILTER). The main format routine (routine code 
PSM$K_MAIN_FORMAT) may not be replaced. 


A user format routine must use the call interface described here. 











FORMAT USER-FORMAT-ROUTINE request_id ,work_area 
func ,func_desc_ 1 
,func_arg_1 ,func_desc_2 
,func_arg_2 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS request_id 
VMS usage: identifier 
type: longword (unsigned) 
access: write only 


mechanism: by reference 


Request identifier supplied by the symbiont when it calls your format routine. 
The request_id argument is the address of a longword containing this 
request identifier value. 


work_area 


VMS usage: address 

type: longword (unsigned) 
access: write only 
mechanism: by reference 


Work area supplied by the symbiont for the use of your format routine. The 
symbiont supplies the address of this area when it calls your routine. The 
work_area argument is a longword containing the address of the work area. 
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The work area is a section of memory that your format routine can use for 
buffering and other internal operations. 


The size of the work area allocated is specified by the work_size argument 
in the PSM$PRINT routine. If you do not specify work_size in the call to 
PSM$PRINT, no work area is allocated. 


In a multithreaded symbiont, a separate work area is allocated for each 
thread. This work area is shared by all user routines. The work area is 
initialized to zero when the symbiont is first started. 


func 

VMS usage: function—_code 
type: longword (unsigned) 
access: write only 


mechanism: by reference 


Function code specifying the service that the symbiont expects your format 
routine to perform. The func argument is the address of a longword into 
which the symbiont writes this function code. 


The function code specifies the reason the symbiont is calling your format 
routine or, in other words, the service that the symbiont expects your routine 
to perform at this time. 


The PSM$K_FORMAT function code is the only one to which your format 
routine must respond. When the symbiont calls your format routine with this 
function code, your routine must move a record from the input buffer to the 
output buffer. 


The symbiont may call your format routine with other function codes. 

Your routine should return the status PSM$_FUNNOTSUP (function not 
supported) when it is called with any of the following function codes or with 
any undocumented function code: 


PSM$K_START_STREAM PSM$K_STOP_STREAM 
PSM$K_START_TASK PSM$K_PAUSE_TASK 
PSM$K_RESUME_TASK PSM$K_STOP_TASK 


PSM$K_RESET_STREAM 


These function codes correspond to message items, which are discussed in 
more detail in Section 9.3.6, sent by the job controller to the symbiont. 


Other function codes correspond to internal symbiont mechanisms that are 
not part of the public interface to the print symbiont. 


Your format routine should return the status PSM$_FUNNOTSUP or 
SS$_NORMAL when it is called with a message function code or with a 
private function code. 


func_desc_1 


VMS usage: char_string 
type: character string 
access: read only 

* mechanism: by descriptor 


Descriptor supplying an input record to be processed by the format routine. 
The func_desc_1 argument is the address of a string descriptor. By using this 
argument, the symbiont supplies the input record that your format routine 

is to process. Because this descriptor may be of any valid string type, your 
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format routine should use the Run-Time Library string routines to analyze 
this descriptor and to manipulate the input record. 


func_arg_1 

VMS usage: vector_byte_unsigned 
type: byte (unsigned) 
access: read only 

mechanism: by reference 


Carriage control for the input record supplied by func_desc_1. The 
func_arg_1 argument is the address of a 4-byte vector that specifies the 
carriage control for the input record. The following diagram depicts the 
format of this 4-byte vector. 


3 2 1 
1 3 5 7 0 
TRAILING CARRIAGE-CONTROL LEADING CARRIAGE-CONTROL 
INFORMATION INFORMATION 


ZK-2009-84 


Bytes 0 and 1 describe the leading carriage control to apply to the input data 
record; bytes 2 and 3 describe the trailing carriage control. 


Byte 0 is a number specifying the number of times the carriage control 
specifier in byte 1 is to be repeated preceding the input data record. Byte 2 is 
a number specifying the number of times the carriage control specifier in byte 
3 is to be repeated following the input data record. 


For values of the carriage control specifier from 1 to 255, the specifier is the 
ASCH character to be used as carriage control. Value 0 represents the ASCII 
“newline” sequence. Newline consists of a carriage return followed by a 
linefeed. 


The func_arg—1 argument is not used if your format routine is an 
output filter routine (routine code PSM$K_OUTPUT_FILTER). See the 
DESCRIPTION section for more information. 


func_desc_2 

VMS usage: char_string 
type: character string 
access: read only 
mechanism: by reference 


Descriptor of a buffer to which your format routine writes the formatted 
output record. The func_desc_2 argument is the address of a string 
descriptor. 


Your format routine must return the formatted data record by using the 
func_desc_2 argument. 


Your format routine should use the Run-Time Library string routines to write 
into the buffer specified by this descriptor. 


PSM-—35 


Print Symbiont Modification (PSM) Routines 
USER-FORMAT-ROUTINE 


func_arg_2 


VMS usage: vector_byte_unsigned 
type: byte (unsigned) 
access: read only 

mechanism: by reference 


Carriage control for the output record returned in func_desc_2. The 
func_arg_2 argument is the address of a 4-byte vector that specifies the 
carriage control for the output record. See the description of func_arg—1 for 
the contents and format of this 4-byte vector. 


If you do not process the carriage-control information supplied in 
func_arg_1 , then you should copy that value into func_arg_2. Otherwise, 
the carriage-control information will be lost. 


The func_arg_2 argument is not used if your format routine is an 
output filter routine (routine code PSM$K_OUTPUT_FILTER). See the 
DESCRIPTION section for more information. 





DESCRIPTION When used, the func_arg_1 argument describes carriage-control information 
for the input data record, and the func_arg_2 argument describes carriage- 
control information for the output data record. 


The input data record is passed to the format routine (input filter or output 
filter) for processing, and the output data record is returned by the format 
routine (input filter or output filter). 


One of the tasks performed by the main format routine (routine code 
PSM$K_-MAIN_FORMAT) is that of embedding the carriage-control 
information (specified by func_arg_1) into the data record (specified by 
func_desc_1). Thus, the output data (specified by func_desc_2) contains 
embedded carriage control and is thus no longer in record format; it is, 
therefore, properly referred to as an output data stream rather than an output 
data record. 


Similarly, the output filter routine (routine code PSM$K_OUTPUT_FILTER), 
which executes after the main format routine, uses neither the func_arg_1 
nor func_arg_2 argument; the data it receives (via func_desc_1) and the 
data it returns (via func_desc_2) are data streams, not data records. 


However, the input filter routine (routine code PSM$K_INPUT_FILTER), 
which executes before the main format routine, uses both func_arg—1 and 
func_arg—2. This is so because the main format routine has not yet executed, 
and so the carriage control information has not yet been embedded in the 
data record. 
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CONDITION SS$_NORMAL S ful. leti Th f 
= uccessful completion. The user format routine 
VALUES has completed the function that the symbiont 
RETURNED requested. . 
PSM$_FUNNOTSUP Function not supported. The user format routine 


does not support or does not recognize the 
function code supplied by the symbiont. To ensure 
future compatibility, your format routine should 
return this status for any unrecognized status 
codes. 


This routine also returns any error condition values that you have coded your 


format routine to return. Refer to Section 10.3.1 for more information about 
error condition values. 
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USER-INPUT-ROUTINE Invoke User-Written Input 
| Routine 
The user-written USER-INPUT-ROUTINE performs input operations. The 


symbiont calls your routine at a specified point in its execution stream; 
you specify this point using the PSM$REPLACE routine. 








FORMAT USER-INPUT-ROUTINE request_id,work_area ,func 
,ftuncdesc ,funcarg 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS request_id 
. VMS usage: identifier 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


Request identifier value supplied by the symbiont when it calls your input 
routine. The request_id argument is the address of a longword containing 
this request identifier value. 


If your input routine initiates an asynchronous operation (for example, 
a call to the $QIO system service), your input routine must copy the 
request identifier value specified by request—id because this value must 
later be passed to the PSM$REPORT routine. See the description of the 
PSM$REPORT routine for more information. 


work_area 


VMS usage: address 

type: longword (unsigned) 
access: write only 
mechanism: by reference 


Work area supplied by the symbiont for the use of your input routine. The 
symbiont supplies the address of this area when it calls your routine. The 
work_area argument is a longword into which the symbiont writes the 
address of the work area. The work area is a section of memory that your 
input routine can use for buffering and for other internal operations. 


The size of the work area allocated is specified by the work_size argument 
in the PSM$PRINT routine. If you do not specify work_size in the call to 
PSM$PRINT, no work area is allocated. 
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In a multithreaded symbiont, a separate work area is allocated for each 
thread. This work area is shared by all user routines. The work area is 
initialized to zero when the symbiont is first started. 


func 

VMS usage: function_code 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Function code supplied by the symbiont when it calls your input routine. The 
func argument is the address of a longword containing this code. 


The function code specifies the reason the symbiont is calling your input 
routine or, in other words, the function that the symbiont expects your 
routine to perform at this time. 


Most function codes require or allow additional information to be passed in 
the call by means of the funcdesc and funcarg arguments. The description of 

_each input function code, therefore, includes a description of how these two 
arguments are used with that function code. 


Following is a list of all the function codes that the symbiont can specify 
when it calls your input routine (function codes applicable only to format 
and output routines are explained in the descriptions of the USER-FORMAT- 
ROUTINE and USER-OUTPUT-ROUTINE, respectively); all function codes 
are defined by the $PSMDEF macro. 


Function Codes for Input Routines 
PSMS$K_CLOSE 


When the symbiont calls your routine with this function code, your routine 
must terminate processing by releasing any resources it may have allocated. 


The symbiont calls your routine with PSM$K_-CLOSE when (1) your routine 
returns from a PSM$K_READ function call with the status PSM$_EOF 

(end of input) or with any error condition, or (2) the symbiont receives a 
task-abortion request from the job controller. 


In any event, the symbiont always calls your input routine with 
PSM$K_CLOSE if your routine returns successfully from a PSM$K_OPEN 
function call. This guaranteed behavior ensures that any resources your 
routine may have allocated on the OPEN will be released on the CLOSE. 


PSM$K_GET_KEY 

Typically, the use of both the PSPM$K_GET_KEY and PSMK$K_POSITION_— 
TO_KEY function codes is appropriate only for a main input routine (routine 
code PSM$K_MAIN_INPUT). 


When the symbiont calls your routine with this function code, your routine 
may do one of two things: (1) return PSM$_FUNNOTSUP (function not 
supported) or (2) return an input marker string to the symbiont. 


If your routine returns PSM$_FUNNOTSUP to this function code, then your 
routine must also return PSM$_FUNNOTSUP if the symbiont subsequently 
calls your routine with the PSM$K_-POSITION_TO_KEY function code. By 
returning PSM$_FUNNOTSUP, your routine is choosing not to respond to 
the symbiont request. 
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If your routine chooses to respond to the PSM$K_GET_KEY function code, 
your routine must return an input marker string to the symbiont; this input 
marker string identifies the input record that your input routine most recently 
returned to the symbiont. Subsequently, when the symbiont calls your input 
routine with the PSM$K_POSITION_TO_KEY function code, the symbiont 
passes your input routine one of the input marker strings that your input 
routine has returned on a previous PSM$K_GET_KEY function call. Using 
this marker string, your input routine must position itself so that, on the next 
PSM$K_READ call from the symbiont, your input routine will return (or 
reread) the input record identified by the marker string. 


Coding your input routine to respond to PPM$K_GET_KEY and PSM$K_— 
POSITION—TO_KEY allows the modified symbiont to perform the file- 
positioning functions specified by the DCL commands START/QUEUE 
/FORWARD, START/QUEUE/ALIGN, START/QUEUE/TOP_OF_FILE, 
START /QUEUE/SEARCH, and START/QUEUE/BACKWARD. These file 
positioning functions also depend on the job controller’s checkpointing 
capability for print jobs. 


Note that your input routine might be called with a marker string that was 
originally returned in a different process context from the current one. This 
can occur because marker strings are sometimes stored in the queue-data file 
across system shutdowns or different invocations of your symbiont. 


The funcdesc argument specifies the address of a string descriptor. Your 
routine must return the marker string by way of this argument. DIGITAL 
recommends that you use one of the Run-Time Library string routines to copy 
the marker string to the descriptor. 


The symbiont periodically calls your input routine with the PSM$K_GET_ 
KEY function code when the symbiont wants to save a marker to a particular 
input record. 


PSM$K_OPEN 


When the symbiont calls your routine with this function code, your routine 
should prepare for input operations by performing such tasks as allocating 
necessary resources, initializing storage areas, opening an input file, and 
so on. Typically, the next time the symbiont calls your input routine, the 
symbiont will specify the PSM$K_READ function code. Note, however, 
that under some circumstances the symbiont might follow an OPEN call 
immediately with a CLOSE call. 


The funcdesc argument points to the name of the file to be opened. Your 
routine can use this file specification or the file identifcation to open the file. 


The funcarg argument specifies the address of a longword. Your input 
routine must return, in this longword, the carriage control type that is to be 
applied to the input records that your input routine will provide. 


The symbiont formatting routine requires this information to determine where 
to apply leading and trailing carriage control characters to the input records 
that your input routine will provide. 


The $PSMDEF macro defines the following four carriage control types. 
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Carriage Type Description 
PSM$K_CC_IMPLIED Implied carriage control. For this type, the symbiont 


inserts a leading linefeed (LF) and trailing carriage 
return (CR) in each input record. This is the default 
carriage control type; it is used if your routine does 
not supply a carriage control type in the funcarg 
argument in response to the PSM$K_OPEN function 
call. 


PSM$K_CC_FORTRAN FORTRAN carriage control. For this type, the 
symbiont extracts the first byte of each input record 
and interprets the byte as a FORTRAN carriage 
control character, which it then applies to the input 
record. 


PSM$K__CC_PRINT PRN carriage control. For this type, the symbiont 
generates carriage control from a 2-byte record 
header that your input routine supplies, with each 
READ call, in the funcarg argument. The funcarg 
argument specifies the address of a longword to 
receive this two-byte header record, which appears 
only in PRN print files. 


PSM$K_CC_INTERNAL Embedded carriage control. For this type, the 
symbiont supplies no carriage control to input 
records. Carriage control is assumed to be embedded 
in the input records. 


PSM$K_POSITION_TO_KEY 


When the symbiont calls your routine with this function code, your routine 
must locate the point in the input stream designated by the marker string that 
your routine returned to the symbiont on the PSM$K_GET_KEY function 
call. 


The next time the symbiont calls your routine, the symbiont specifies the 
PSM$K_READ function call, expecting to receive the next sequential input 
record. After rereading this record, subsequent READ calls proceed from this 
new position of the file. This is not a one-time rereading of a single record 
but a repositioning of the file. The symbiont calls your routine with this 
function code when the job controller receives a request to resume printing at 
a particular page. 


Refer to the description of the PSM$K_GET_KEY for more information. 


PSM$K_READ 


When the symbiont calls your routine with this function code, your routine 
must return an input record. The symbiont repeatedly calls your input routine 
with the PSM$K_READ function code until (1) your routine indicates end 
of input by returning the status PSM$_EOF, (2) your routine or another 
routine returns an error status, or (3) the symbiont receives an asynchronous 
task-abortion request from the job controller. 


The funcdesc argument specifies the address of a string descriptor. Your 
routine must return the input record by using this argument. DIGITAL 
recommends that you use one of the Run-Time Library string routines to copy 
the input record to the descriptor. 
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The funcarg argument specifies the address of a longword. This argument 

is used only if the carriage control type returned by your input routine on 
the PSM$K_OPEN function call was PSM$K_CC_PRINT. In this case, your 
input routine must supply, in the funcarg argument, the 2-byte record header 
found at the beginning of each input record. 


PSMS$K_REWIND 


When the symbiont calls your routine with this function code, your routine 
must do one of two things: (1) return PSM$_FUNNOTSUP (function not 
supported) or (2) locate the point in the input stream designated as the 
beginning of the file. 


If your routine returns PSM$_FUNNOTSUP to this function code, then 

the symbiont subsequently calls your input routine with a PSM$K_-CLOSE 
function call followed by a PSM$K_OPEN function call. By returning 
PSM$K_FUNNOTSUP, your routine is choosing not to support the 
repositioning of the input service to the beginning of the file. The symbiont, 
therefore, performs the desired function by closing and then reopening the 
input routine. 


You cannot use the funcdesc and the funcarg arguments with this function 
code. 


This function call allows the modified symbiont to perform the file-positioning 
functions specified by the DCL commands START/QUEUE/TOP_OF_FILE, 
START/QUEUE/FORWARD, START /QUEUE/BACKWARD, START /QUEUE 
/SEARCH, and START/QUEUE/ALIGN. This is a required repositioning of 
the file. 


Other Input Function Codes 

The symbiont may call your input routine with other function codes. Your 
routine must return the status PSM$_FUNNOTSUP (function not supported) 
when it is called with any of the following function codes or with any 
undocumented function code: 


PSM$K_START_STREAM PSM$K_STOP_STREAM 
PSM$K_START_TASK PSM$K_PAUSE_TASK 
PSM$K_RESUME _TASK PSM$K_STOP_TASK 


PSM$K__RESET_STREAM 


These function codes correspond to message items, which are discussed in 
detail in Section 10.3.5, sent by the job controller to the symbiont. 


Other function codes correspond to internal symbiont mechanisms that are 
not part of the public interface to the print symbiont. 


Your input routine should return the status PSM$K_FUNNOTSUP or 
SS$_NORMAL when it is called with a message function code or with a 
private function code. 


funcdesc 

VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor 


Function descriptor supplying information related to the function specified by 
the func argument. The funcdesc argument is the address of this descriptor. 
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The contents of the function descriptor vary for each function. Refer to the 
description of each function code to determine the contents of the function 
descriptor. In some cases, the function descriptor is not used at all. 


funcarg 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Function argument supplying information related to the function specified 
by the func argument. The funcarg argument is the address of a longword 
containing this function argument. This argument can be an input or an 
output argument, depending on the function request, but is usually used as 
an output argument. 





CONDITION 
VALUES 
RETURNED 


SS$_NORMAL Successful completion. The user input routine 
has completed the function that the symbiont 
requested. 

PSM$_FLUSH Flush output stream. The user input routine 


can return this status only when called with the 
PSM$K_READ function code. When this status 
is returned to the symbiont, the symbiont stops 
calling the input routine with the PSM$K_READ 
function code until all outstanding format and 
output operations have completed. 


PSM$_FUNNOTSUP Function not supported. The user input routine 
does not support or does not recognize the 
function code supplied by the symbiont. To ensure 
future compatibility, your input routine should 
return this status for any unrecognized status 
codes. . 


PSM$_PENDING Requested function accepted but not completed. 
Your input routine can return this status only 
with the PSM$K_READ function call. Further, 
if your routine returns PSM$_PENDING, your 
routine must eventually signal completion via the 
PSM$REPORT routine. Refer to the description 
of the PSM$REPORT routine for more information 
about asynchronous operations and the 
PSM$_PENDING condition value. 


This routine also returns any error condition values that you have coded your 


format routine to return. Refer to Section 10.3.1 for more information about 
error condition values. 
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USER-OUTPUT-ROUTINE Invoke User-Written 
Output Routine 
The ieeeonition USER-OUTPUT-ROUTINE performs output operations. 


You supply a user output routine by calling the PSM$REPLACE routine 
with the routine code PSM$K_OUTPUT. 





FORMAT USER-OUTPUT-ROUTINE  request_id ,work_area ,func 
,funcdesc ,funcarg 





RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS request_id 


VMS usage: identifier 

type: longword (unsigned) 
access: write only 
mechanism: by reference 


Request identifier value supplied by the symbiont when it calls your output 
routine. The request_id argument is the address of a longword containing 
this value. 


If your output routine initiates an asynchronous operation (for example, a 
call to the Queue I/O Request (SYS$QIO) system service), you must save the 
request_id argument because you will need to store the request identifier 
value for later use with the PSM$REPORT routine. See the description of the 
PSM$REPORT routine for more information. 


work_area 


VMS usage: address 

type: longword (unsigned) 
access: write only 
mechanism: by reference 


Work area supplied by the symbiont for the use of your format routine. The 
symbiont supplies the address of this area when it calls your routine. The 
work_area argument is a longword containing the address of the work area. 
The work area is a section of memory that your format routine can use for 
buffering and other internal operations. 


The size of the work area allocated is specified by the work—size argument 
in the PSM$PRINT routine. If you do not specify work—size in the call to 
PSM$PRINT,.no work area is allocated. 
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In a multithreaded symbiont, a separate work area is allocated for each 
thread. This work area is shared by all user routines. The work area is 
initialized to zero when the symbiont is first started. 


func 

VMS usage: function_code 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Function code supplied by the symbiont when it calls your output routine. 
The func argument is the address of a longword containing this code. 


The function code specifies the reason the symbiont is calling your output 
routine or, in other words, the function that the symbiont expects your 
routine to perform at this time. 


Most function codes require or allow additional information to be passed in 
the call via the funcdesc and funcarg arguments. The description of each 
output function code, therefore, includes a description of how these two 
arguments are used for that function code. 


The following list describes all the function codes that the symbiont may 
supply when it calls your output routine (function codes applicable only to 
input and formatting routines are explained in the descriptions of the user 
input routine and user formatting routine, respectively); all function codes are 
defined by the $PSMDEF macro. 


Function Codes for Output Routines 
PSM$K_OPEN 


When the symbiont calls your output routine with this function code, your 
routine should prepare to move data to the device by performing such tasks 
as allocating the device, assigning a channel to the device, and so on. The 
next time the symbiont calls your output routine, the symbiont specifies 
one of the WRITE function codes (PSM$K_WRITE or PSM$K_WRITE_— 
NOFORMAT). 


The symbiont calls your output routine with the PSM$K—OPEN function 
code when the symbiont receives the SMBMSG$K_START_STREAM 
message from the job controller. 


If your output routine returns an error condition value (low bit clear) to 
the PSM$K_OPEN function call, the job controller stops processing on the 
stream and reports the error to whomever entered the DCL command 
START /QUEUE. 


The funcdesc argument is the address of a descriptor that identifies the name 
of the device the output routine is to write to. This device name is established 
by the DCL command INITIALIZE/QUEUE/ON=device-name. 


The funcarg argument is the address of a longword into which the user 
output routine returns the device status longword. For the contents of 

the device status longword, refer to the description of the SMBMSG$K_ 
DEVICE_STATUS item in the SMB$READ_MESSAGE_ITEM routine, which 
is documented in Chapter 11. 
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Your output routine sets bits in the device status longword to indicate to the 
job controller whether the device falls into one of the following categories: 


¢ Can print lowercase letters 
e Is a terminal 


e Is connected to the CPU by means of a modem (remote) 


If your output routine does not set any of these bits in the device status 
longword, the job controller assumes, by default, that the device is a line 
printer that prints only uppercase letters. 


PSM$K_WRITE 

When the symbiont calls your routine with this function code, your routine 
must write data to the device. The symbiont supplies the data to be written 
in the funcdesc argument. DIGITAL recommends that you use one of the 
Run-Time Library string routines to access the data in the buffer described by 
the funcdesc argument. 


PSM$K_WRITE_NOFORMAT 

When the symbiont calls your routine with this function code, your routine 
must write data to the device and must indicate to the device driver that the 
data is not to be formatted. 


The symbiont calls your routine with this function code when (1) the print 
request specifies the PASSALL option or (2) data is introduced by the ANSI 
DCS (device control string) escape sequence. 


The symbiont supplies the data to be written in the funcdese argument. 
DIGITAL recommends that you use one of the Run-Time Library string 
routines to move the data from the descriptor to the device. 


The output routine of the symbiont informs the device driver not to format 
the data in the following way: 


e When the device is a line printer, the symbiont’s output routine specifies 
the IO$_WRITEPBLK function code when it calls the $QIO system 
service. 


¢ When the device is a terminal, the symbiont’s output routine specifies 
the IO$M_NOFORMAT function modifier when it calls the $QIO system 
serivce. 


PSMS$K_CANCEL 


When the symbiont calls your routine with this function code, your routine 
must abort any outstanding asynchronous I/O requests. 


The output routine supplied by the symbiont aborts outstanding I/O requests 
by calling the $QIO system service with the IO$_CANCEL function code. 


If your output routine returned the condition value PSM$_PENDING to 
one or more previous write requests that are still outstanding (that is, 
PSM$REPORT has not yet been called to report completion), then your 
output routine must call PSM$REPORT one time for each outstanding write 
request that is canceled with this call. That is, canceling an asynchronous 
write request does not relieve the user output routine of the requirement to 
call PSM$REPORT once for each asynchronous write request. 


You cannot use the funcdesc and funcarg arguments with this function code. 
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PSM$K_CLOSE 


When the symbiont calls your routine with this function code, your output 
routine must terminate processing and release any resources it allocated (for 
example, channels assigned to the device). 


You cannot use the funcdesce and funcarg arguments with this function code. 


Other Output Function Codes 

The symbiont may call your output routine with other function codes. 

Your routine should return the status PSM$_FUNNOTSUP (function not 
supported) when it is called with any of the following function codes or with 
any undocumented function code: 


PSM$K_START_STREAM PSM$K_STOP_STREAM 
PSM$K_START_TASK PSM$K_PAUSE_TASK 
PSM$K_RESUME_TASK PSM$K_STOP_TASK 


PSM$K_RESET_STREAM 


These function codes correspond to message items, which are discussed in 
more detail in Section 11.1.6, sent by the job controller to the symbiont. 


Other function codes correspond to internal symbiont mechanisms that are 
not part of the public interface to the print symbiont. 


Your output routine should return the status PSM$K_FUNNOTSUP or 
SS$_NORMAL when it is called with a message function code or with a 
private function code. 


funcdesc 

VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor 


Function descriptor supplying information related to the function specified by 
the func argument. The funcdesc argument is the address of this descriptor. 


The contents of the function descriptor vary for each function. Refer to the 
description of each function code to determine the contents of the function 
descriptor. In some cases, the function descriptor is not used at all. 


funcarg 

VMS usage: user_arg 

type: longword (unsigned) 
access: read only 


mechanism: by reference 


Function argument supplying information related to the function specified 
by the func argument. The funcarg argument is the address of a longword 
containing this function argument. 


The contents of the function argument vary for each function. Refer to the 
description of each function code to determine the contents of the function 
argument. In some cases, the function argument is not used. 
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CONDITION 
VALUES | 
RETURNED 
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SS$_NORMAL 


PSM$_FUNNOTSUP 


PSM$_PENDING 


Successful completion. The user output routine 
has completed the function that the symbiont 
requested. 


Function not supported. The user output routine 
does not support or does not recognize the 
function code supplied by the symbiont. To ensure 
future compatibility, your output routine should 
return this status for any unrecognized status 
codes. 


Requested function accepted but not completed. 
Your output routine can return this status only 
with PSM$K_WRITE and PSM$K_WRITE_ 
NOFORMAT function calls. Further, if your 
routine returns PSM$_PENDING, your routine 
must eventually signal completion by way of the 
PSM$REPORT routine. Refer to the description 
of the PSM$REPORT routine for more information 
about asynchronous write operations and the 
PSM$_PENDING condition value. 


This routine also returns any error condition values that you have coded your 
output routine to return. Refer to Section 10.3.1 for more information about 


error condition values. 
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11.1 Introduction to SMB Routines 


The Symbiont/Job Controller Interface (SMB) routines provide the interface 
between the job controller and symbiont processes. A user-written symbiont 
must use these routines to communicate with the VMS job controller. 


Always use the SMB interface routines or SYS$SNDJBC system service to 
communicate with the job controller. You need not and should not attempt 
to communicate directly with the job controller. 


To write your own symbiont, you need to understand how symbionts work 
and, in particular, how the standard VMS print symbiont behaves. 


11.1.1 Types of Symbiont 


There are two types of symbiont: 


Device symbiont, either an input symbiont or an output symbiont. An 
input symbiont is one that transfers data from a slow device to a fast 
device, for example, from a card reader to a disk. A card-reader symbiont 
is an input symbiont. An output symbiont is one that transfers data from 
a fast device to a slow device, for example, from a disk to a printer or 
terminal. A print symbiont is an output symbiont. 


Server symbiont, a symbiont that processes or transfers data but is not 
associated with a particular device; one example is a symbiont that 
transfers files across a network. - 


The VMS operating system does not supply any server symbionts. 


11.1.2 Symbionts Supplied with the VMS Operating System 
The VMS operating system supplies two symbionts: 


SYS$SYSTEM:PRTSMB.EXE (PRTSMB for short), an output symbiont for 
use with printers and printing terminals. 


PRTSMB performs such functions as inserting flag, burst, and trailer pages 
into the output stream; reading and formatting input files; and writing 
formatted pages to the printing device. 


You can modify PRTSMB using the Print Symbiont Modification (PSM) 
routines. 


SYS$SYSTEM:INPSMB.EXE (INPSMB for short) an input symbiont for 
use with card readers. 


This symbiont handles the transferring of data from a card reader to 
a disk file. You cannot modify INPSMB, nor can you write an input 
symbiont using the SMB routines. 
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11.1.3 Symbiont Behavior in the VMS Environment 


SMB-2 


In the VMS environment, a symbiont is a process under the control of the 
VMS job controller that transfers or processes data. 


Figure 11-1 depicts the VMS components that take part in the handling of 
user requests that involve symbionts. This figure shows two symbionts: (1) 
the print symbiont supplied by the VMS operating system, PRTSMB, and (2) 
a user-written symbiont, GRAPHICS.EXE, which services a graphics plotter. 
The numbers in the figure correspond to the numbers in the list that follows. 


This list does not reflect the activities that must be performed by the 
hypothetical, user-written symbiont, GRAPHICS.EXE. This symbiont is 
represented in the figure to illustrate the correspondence between a user- 
written symbiont and the print symbiont supplied by the VMS operating 
system. 


Although SMB routines can be used for a different kind of symbiont, many 
of their arguments and associated symbols have names related to the print 
symbiont. The print symbiont is presented here as an example of a typical 
symbiont and illustrates points that are generally true for symbionts. 


@ You request a printing job with the DCL command PRINT. DCL calls 
the Send to Job Controller (SYS$SNDJBC) system service, passing the 
name of the file to be printed to the job controller, along with any other 
information specified by qualifiers for the PRINT command. 


@ The job controller places the print request in the appropriate queue and 
assigns the request a job number. 


© The job controller breaks the print job into a number of tasks (for 
example, printing three copies of the same file is three separate tasks). 
The job controller makes a separate request to the symbiont for each task. 


Each request that the job controller makes consists of a message. Each 
message consists of a code that indicates what the symbiont is to do and 
a number of items of information that the symbiont needs to carry out 
the task (the name of the file, the name of the user, and so on.) 


@ PRTSMB interprets the information it receives from the job controller. 


@ PRTISMB locates and opens the file it is to print by using the file- 
identification number the job controller specified in the start-task message. 


@ PRTSMB sends the data from the file to the printer’s driver. 


@ The device driver sends the data to the printer. 
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Figure 11-1 Symbionts in the VMS Operating System Environment 
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11.1.4 Writing a Symbiont 


Writing your own symbiont permits you to use the queueing mechanisms 
and control functions of the VMS job controller. You might want to do this 
if you need a symbiont for a device that cannot be served by PRTSMB (or a 
modified form of PRTSMB) or if you need a server symbiont. The interface 
between the job controller and the symbiont permits the symbiont you write 
to use the many features of the job controller. 


For example, when you use the DCL command PRINT to print a file, the job 
controller sends a message to the print symbiont telling it to print the file. 
However, when a user-written symbiont receives the same message (caused 
by entering a PRINT command), it might interpret it to mean something quite 
different. A robot symbiont, for example, might interpret the message as a 
command for movement and the file specification (specified with the PRINT 
command) might be a file describing the directions in which the robot is to 
move. 
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Note: Modifying PRTSMB is easier than writing your own symbiont; choose 
this option if possible. The Print Symbiont Modification (PSM) routines 
describe how to modify PRTSMB to suit your needs. 


11.1.5 Guidelines for Writing a Symbiont 


Although you can write a symbiont to use the queuing mechanisms and other 
features of the job controller in whatever way you want, you must follow 
these guidelines to ensure that your symbiont works correctly: 
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The symbiont must not use any of the process-permanent channels, 
which are assigned to the following logical names: 


SYS$INPUT 
SYSSOUTPUT 
SYS$ERROR 
SYS$COMMAND 


The symbiont must allocate and deallocate memory using the RTL 
routines LIB$GET_VM and LIB$FREE_VM. 


To be compatible with future releases of the VMS operating system, 
you should write the symbiont to ignore unknown message-item codes 
and unknown message-request codes. (See the SMB$READ_ITEM_ 
MESSAGE routine.) 


The symbiont must communicate with the job controller by using the Job- 
Controller/Symbiont Interface (SMB) routines and the $SNDJBC system 
service. 


The symbiont should not perform lengthy operations within the context 
of an AST routine. The symbiont can receive messages only from the job 
controller when it is not executing within the context of an AST routine. 


To assign a symbiont to a queue after it is compiled and linked, the 
executable image of the symbiont must reside in SYS$SYSTEM, and you 
must enter either of the following commands: 

$ INITIALIZE/QUEUE/PROCESSOR=symbiont_filename 

$ START/QUEUE/PROCESSOR=symbiont_filename 

You should specify only the file name in the command. The disk and 


directory default to SYS$SYSTEM, and all fields except the file name are 
ignored. 
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11.1.6 The Symbiont/Job-Controller Interface Routines 


The five SMB routines form a public interface to the VMS job controller. The 
job controller delivers requests to symbionts by means of this interface, and 
the symbionts communicate their responses to those requests through this 
interface. A user-written symbiont uses the following routines to exchange 
messages with the job controller: 


SMBSINITIALIZE Initializes the SMB facility’s internal database, 
establishes the interface to the job controller, 
and defines whether 


e Messages from the job controller are to be 
delivered to the symbiont synchronously 
or asynchronously with respect to 
execution of the symbiont. 


e The symbiont is to be single-threaded 
or multithreaded; these concepts are 
described in the sections that follow. 


SMBS$CHECK __FOR_MESSAGE Checks to see if a message from the job 
controller to the symbiont has arrived 

SMB$READ_MESSAGE Reads the job controller's message into a 
buffer 

SMBSREAD_MESSAGE_ITEM Returns one item of information from the job 
controller's message (which can have several 
informational items) 


SMB$SEND_TO_JOBCTL Sends a message from the symbiont to the 
job controller 


The following sections discuss how to use the SMB routines when writing 
your symbiont. 


11.1.7 Choosing the Symbiont Environment 


11.1.7.1 


The first SMB routine that a symbiont must call is the SMB$INITIALIZE 
routine. In addition to allocating and initializing the SMB facility’s internal 
database, it offers you two options for your symbiont environment: 
synchronous or asynchonous delivery of messages from the job controller, 
and single streaming or multistreaming the symbiont. 


Synchronous Versus Asynchronous Delivery of Requests 

When you initialize your job controller/symbiont interface, the symbiont 
has the option of accepting requests from the job controller sychronously or 
asynchronously. 


Synchronous Environment 


The address of an AST routine is an optional argument to the 
SMBS$INITIALIZE routine; if it is not specified, the symbiont receives 
messages from the job controller synchronously. A symbiont that receives 
messages synchronously must call SMB$CHECK_FOR_MESSAGE 
periodically during the processing of tasks in order to ensure the timely 
delivery of STOP_TASK, PAUSE_TASK, and RESET_STREAM requests. 
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SMB$CHECK_FOR—MESSAGE checks to see if a message from the job 
controller is waiting. If a message is waiting, SMB$CHECK_FOR—MESSAGE 
returns a success code. The caller of SMB$CHECK_FOR_MESSAGE 

can then call SMB$READ_MESSAGE to read the message and take the 
appropriate action. 


If no message is waiting, SMB$CHECK_FOR_MESSAGE returns a zero in 
RO. The caller of SMB$CHECK_FOR_MESSAGE can continue to process the 
task at hand. 


Figure 11-2 is a flowchart for a synchronous, single-threaded symbiont. 
The flowchart does not show all the details of the logic the symbiont needs 
and does not show how the symbiont handles pause-task, resume-task, or 
reset-stream requests. 


Asynchronous Environment 


To receive messages asynchronously, a symbiont specifies a message-handling 
AST routine as the second argument to the SMB$INITIALIZE routine. In this 
scheme, whenever the job controller sends messages to the symbiont, the 
AST routine is called. 


The AST routine is called with no arguments and returns no value. You have 
the option of having the AST routine read the message within the context of 
its execution or of having the AST routine wake a suspended process to read 
the message outside the context of the execution of the AST routine. 


Be aware that an AST can be delivered only while the symbiont is not 
executing within the context of an AST routine. Thus, in order to ensure 
delivery of messages from the job controller, the symbiont should not perform 
lengthy operations at AST level. 


This is particularly important to the execution of STOP_TASK, PAUSE 
TASK, and RESET_STREAM requests. If a STOP_TASK request cannot be 
delivered during the processing of a task, for example, it is useless. 


One technique that ensures delivery of STOP and PAUSE requests in an 
asynchronous environment is to have the AST routine set a flag if it reads a 
PAUSE_TASK, STOP_TASK, or a RESET_STREAM request and to have the 
symbiont’s main routine periodically check the flag. 


Figure 11-3 shows a logic chart for a single-threaded, asynchronous symbiont. 
The figure does not show many details that your symbiont might include, 
such as a call to the $QIO system service. 


Note that the broken lines that connect the calls to SYS$HIBER with the 
AST routine’s calls to SYS$WAKE show that the next action to take place is 
the call to SYS$WAKE. They do not accurately represent the flow of control 
within the symbiont but represent the action of the job controller in causing 
the AST routine to execute. 
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Figure 11—2 Flowchart for a Single- Threaded, Synchronous Symbiont 
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Figure 11-3 Flow Chart for a Single-Threaded, Asynchronous 
Symbiont 
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Figure 11—3 (Cont.) Flow Chart for a Single-Threaded, 
Asynchronous Symbiont 
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Single-Streaming Versus Multistreaming 

A single-stream (or thread) is a logical link between a queue and a symbiont 
process. When a symbiont process is linked to more than one queue and 
serves those queues simultaneously, it is called a multithreaded symbiont. 


The argument to the SMB$READ_MESSAGE routine provides a way for a 
multithreaded symbiont to keep track of the stream referred to by a request. 
Writing your own multithreaded symbiont, however, can be a complex 
undertaking. 


11.1.8 Reading Job Controller Requests 
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There are seven general functions that the job controller can request of the 
symbiont: 


SMBMSG$K_START_STREAM SMBMSG$K_STOP_STREAM 
SMBMSG$K_START_TASK SMBMSG$K_PAUSE_TASK 
SMBMSG$K_RESUME_TASK SMBMSG$K_STOP_TASK 


SMBMSG$K_RESET_STREAM 


The job controller passes these requests to the symbiont in a structure that 
contains (1) a code that identifies the requested function and (2) optional 
items of information that the symbiont might need to perform the requested 
function. 


By calling SMBSREAD_MESSAGE, the symbiont reads the function code 
and writes the associated items of information, if any, into a buffer. The 
symbiont then parses the message items stored in the buffer by calling the 
SMB$READ_MESSAGE_ITEM routine. SMB$READ_MESSAGE_ITEM 
reads one message item each time it is called. 


Each message item consists of a code that identifies the type of information 
the item contains, and the information itself. For example, the SMB$K_JOB_ 
NAME code tells the symbiont that the item contains a string, which is the 
name of a job. 


The number of message items in a request message varies with each type of 
request. Therefore, to ensure that all message items are read, SMBSREAD_ 
MESSAGE_ITEM must be called repeatedly for each request. SMBSREAD_ 
MESSAGE~_ITEM returns status SMB$_NOMOREITEMS after it has read the 
last message item in a given request. 


Typically, a symbiont checks the code of a message item against a case table 
and stores the message string in an appropriate variable until all the message 
items are read and the processing of the request can begin. 


See the description of the SMB$READ_MESSAGE_ITEM routine for a table 
that shows the message items that make up each type of request. 
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11.1.9 Processing Job Controller Requests 


After a request is read, it must be processed. The way a request is processed 
depends on the type of request. The following section lists, for each request 
that the job controller sends to the print symbiont, the actions that the 
standard symbiont (PRTSMB) takes when the message is received. These 
actions are oriented toward print symbionts in particular but can serve as a 
guideline for other kinds of symbionts as well. 


The symbiont you write can respond to requests in a similar way or in 

a different way appropriate to the function of your symbiont. DIGITAL 
suggests that your routines follow the guidelines described in this document. 
(Note that the behavior of the standard symbiont is subject to change without 
notice in future versions of the VMS operating system.) 


SMBMSG$K_START_STREAM 


e Reset all stream-specific information that might have been altered by 
previous START_STREAM requests on this stream (for multithreaded 
symbionts). 


e Read and store the message items associated with the request. 

¢ Allocate the device specified by the SMBMSG$K_DEVICE_NAME item. 
e Assign a channel to the device. 

e Obtain the device characteristics. 


e If the device is neither a terminal nor a printer, then abort processing 
and return an error to the job controller by means of the SMB$SEND... 
TO_JOBCTL routine. Note that, even though an error has occurred, the 
stream is still considered started. The job controller detects the error and 
sends a STOP_STREAM request to the symbiont. 


e Set temporary device characteristics suited to the way the symbiont will - 
use the device. 


e For remote devices (devices connected to the system by means of a 
modem) establish an AST to report loss of the carrier signal. 


e Report to the job controller that the request has been completed and that 
the stream is started, by specifying SMBMSG$K_START_STREAM in the 
call to SMB$SEND_TO_JOBCTL. 


SMBMSG$K_START_TASK 


¢ Reset all task-specific information that might have been altered by 
previous START_TASK requests on this stream number. 


e Read and store the message items associated with the request. 
e¢ Open the main input file. 


¢ Report to the job controller that the task has been started by specifying 
SMBSMG$K_START_TASK in the call to the SMB$SEND._.TO_JOBCTL 
routine. 


e Begin processing the task. 


e When the task is complete, notify the job controller by specifying 
SMBMSG$K_TASK—COMPLETE in the call to the SMBSSEND_TO_ 
JOBCTL routine. 
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SMBMSG$K_PAUSE_TASK 


Read and store the message items associated with the request. 


Set a flag that will cause the main processing routine to pause at the 
beginning of the next output page. 


When the main routine pauses, notify the job controller by specifying 
SMBMSG$K_PAUSE_TASK in the call to the SMB$SEND_TO_JOBCTL 
routine. 


SMBMSG$K_RESUME_TASK 


Read and store the message items associated with the request. 
Perform any positioning functions specified by the message items. 


Clear the flag that causes the main input routine to pause, and resume 
processing the task. 


Notify the job controller that the task has been resumed by specifying 
SMBMSG$K_RESUME_TASK in the call to the SMBSSEND_TO_. 
JOBCTL routine. 


SMBMSG$K_STOP_TASK 


Read and store the message items associated with the request. 
If processing of the current task has paused, then resume it. 
Cancel any outstanding I/O operations. 

Close the input file. 


If the job controller specified, in the START_TASK message, that a trailer 
page should be printed when the task is stopped or if it specified that 
the device should be reset when the task is stopped, then perform those 
functions. 


Notify the job controller that the task has been stopped abnormally by 
specifying SMBMSG$K_STOP_TASK and by specifying an error vector in 
the call to SMB$SEND_TO_JOBCTL. PRTSMB specifies the value passed 
by the job controller in the SMBMSG$K_STOP_CONDITION item as the 
error condition in the error vector. 


SMBMSG$K_STOP_STREAM 


Read and store the message items associated with the request. 


Release any stream-specific resources: (1) deassign the channel to the 
device, and (2) deallocate the device. 


Notify the job controller that the stream has been stopped by specifying 
SMBMSG$K_STOP_STREAM in the call to SMB6SEND_TO_JOBCTL. 


If this is a single-threaded symbiont or if this is a multithreaded symbiont 
but all other streams are currently stopped, then call the SYS$EXIT 
system service with the condition code SS$_NORMAL. 
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SMBMSG$K_RESET_STREAM 
¢ Read and store the message items associated with the request. 


e Abort any task in progress—you do not need to notify the job controller 
that the task has been aborted, but you can do so if you want. 


e If the job controller specified, in the START_TASK message, that a trailer 
page should be printed when the task is stopped or if it specified that 
the device should be reset when the task is stopped, then suppress those 
functions. 


The job controller sends the symbiont a RESET_STREAM request to 
regain control of a queue or a device that has failed to respond to 

a STOP_TASK request. The RESET_STREAM request should avoid 

any further I/O activity if possible. The printer might be disabled, for 
example, and requests for output on that device will never be completed. 


e Continue as if this were a STOP_STREAM request. 


Note: A STOP_STREAM request and a RESET_STREAM request each stop the 
queue; but a RESET_STREAM request is an emergency stop and is used, 
for example, when the device has failed. A RESET_STREAM request 
should prevent any further I/O activity because the printer might not be 
able to complete it. 


11.1.10 Responding to Job Controller Requests 


The symbiont uses the SMB$SEND_TO_JOBCTL routine to send messages 
to the job controller. 


Most messages that the symbiont sends to the job controller are responses to 
requests made by the job controller. Such messages inform the job controller 
that the request has been completed successfully or unsuccessfully. The 
function code that the symbiont returns to the controller in the call to 
SMB$SEND_TO_JOBCTL indicates what request has been completed. 


For example, if the job controller sends a START_TASK request using 

the SMBMSG$K_START_TASK code, the symbiont responds by calling 
SMB$SEND_TO_JOBCTL using SMBMSG$K_START_TASK as the request 
argument to indicate that task processing has begun. Until the symbiont 
responds, the DCL command SHOW QUEUE indicates that the queue is 
starting. 


The responses to some requests use additional arguments to send more 
information than just the request code. See the SMB$SEND_TO_JOBCTL 
routine for a table showing the additional arguments allowed in response to 
each request. 


In addition to sending messages in response to requests, the symbiont can 
send other messages to the job controller. In these messages the symbiont 
sends either the SMBMSG$K_TASK_COMPLETE code, indicating that it 
has completed a task, or SMBMSG$K_TASK_STATUS, indicating that the 
message contains information on the status of a task. 


Note that, when a START_TASK request is delivered, the symbiont responds 
with a SMB$SEND_TO_JOBCTL message with the SMBSMG$K_START_. 
TASK code. This response means the task has been started. It does not mean 
the task has been completed. When the symbiont completes the task, it calls 
SMB$SEND_TO_JOBCTL with the SMBSMG$K_TASK_COMPLETE code. 
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SMB Routines 


The following pages describe the individual SMB routines. 
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SMB$CHECK_FOR_MESSAGE Check for 
Message from 
Job Controller 


The SMB$CHECK__FOR_.MESSAGE routine determines whether a message 
sent from the job controller to the symbiont is waiting to be read. 








FORMAT SMBS$CHECK_FOR_MESSAGE 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS ~ None. 





DESCRIPTION — When your symbiont calls the SMB$INITIALIZE routine to initialize the 
interface between the symbiont and the job controller, you can choose to 
have requests from the job controller delivered by means of an AST. If 
you choose not to use ASTs, your symbiont must call SMB$CHECKFOR_ 
MESSAGE during the processing of tasks in order to see if a message from the 
job controller is waiting to be read. If a message is waiting, SMB$CHECK_— 
FOR—MESSAGE returns a success code; if not, it returns a zero. 


If a message is waiting, the symbiont should call SMB$READ_MESSAGE to 
read it and determine if immediate action should be taken (as in the case of 
STOP_TASK, RESET_STREAM or PAUSE_TASK). 


If a message is not waiting, SMB$CHECK_MESSAGE returns a zero. If this 
condition is detected, the symbiont should continue processing the request at 





hand. 
CONDITION ; 
VALUES SS$_NORMAL One or more messages waiting. 
RETURNED 0 No messages waiting. 
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SMBSINITIALIZE Initialize User-Written Symbiont 


The SMB$INITIALIZE routine initializes the user-written symbiont and 
the interface between the symbiont and the job controller. It allocates 
and initializes the internal databases of the interface and sets up the 
mechanism that is to wake up the symbiont when a message is received. 





FORMAT 


SMBSINITIALIZE — structure_level [,ast_routine] 
[streams] 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 
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structure_level 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Version of the job-controller/symbiont interface. The structure_level 
argument is the address of a longword containing the version of the job- 
controller/symbiont interface used when the symbiont was compiled. Always 
place the value of the symbol SMBMSG$K_STRUCTURE_LEVEL in the 
longword addressed by this argument. This symbol is defined by the 
$SMBDEF macro. The $SMBDEF macro is defined in the macro library 
SYS$LIBRARY:LIB.MLB. 


ast_routine 

VMS usage: ast—procedure 

type: procedure entry mask 
access: read only 


mechanism: by reference 


Message-handling routine called at AST level. The ast_routine argument is 
the address of the entry point of the message-handling routine to be called at 
AST level when the symbiont receives a message from the job controller. The 
AST routine is called with no parameters and returns no value. If an AST 
routine is specified, the routine is called once each time the symbiont receives 
a message from the job controller. 


The AST routine typically reads the message and determines if immediate 
action must be taken. Be aware that an AST can be delivered only while the 
symbiont is operating at non-AST level. Thus, to ensure delivery of messages 
from the job controller, the symbiont should not perform lengthy operations 
at AST level. 
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The ast_routine argument is optional. If you do not specify it, the symbiont 
must call the SMBS¢CHECK_FOR_MESSAGE routine to check for waiting 
messages. 


streams 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Maximum number of streams the symbiont is to support. The streams 
argument is the address of a longword containing the number of streams that 
the symbiont is to support. The number must be in the range 1 to 16. 


If you do not specify this argument, a default value of 1 is used. Thus, 
by default, a symbiont supports one stream. Such a symbiont is called a 
single-threaded symbiont. 


A stream (or thread) is a logical link between a queue and a symbiont. 
When a symbiont is linked to more than one queue, and serves those queues 
simultaneously, it is called a multithreaded symbiont. 





DESCRIPTION 


Your symbiont must call SMB$INITIALIZE before calling any other SMB$ 
routines. It calls SMB$INITIALIZE in order to do the following: 


e Allocate and initialize the SMBS facility’s internal database. 
e Establish the interface between the job controller and the symbiont. | 
e¢ Determine the threading scheme of the symbiont. 


¢ Set up the mechanism to wake your symbiont when a message is 
received. 


After the symbiont calls SMB$INITIALIZE, it can communicate with the job 
controller using the other SMB$§ services. 





CONDITION 
VALUES 
RETURNED 


SS$_NORMAL Routine successfully completed. 
SMB$_INVSTRLEV Invalid structure level. 


This routine also returns any codes returned by $ASSIGN and LIB$GET_VM. 
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SMBS$READ_MESSAGE Obtain Message Sent by 
Job Controller 


The SMB$READ_MESSAGE routine copies a message that the job 
controller has sent into the caller’s specified buffer. 








FORMAT SMB$READ_MESSAGE stream , buffer ,request 
RETURNS. VMS usage: cond_value 

type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS stream 
VMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


Stream number specifying the stream to which the message refers. The 
stream argument is the address of a longword into which the job controller 
writes the number of the stream referred to by the message. In single- 
threaded symbionts, the stream number is always 0. 


buffer 

VMS usage: char_string 
type: character string 
access: write only 


mechanism: by descriptor 


Address of the descriptor that points to the buffer into which the job 
controller writes the message. SMBSREAD_MESSAGE uses the RTL STR$ 
string-handling routines to copy the message into the buffer you supply. The 
buffer should be specified by a dynamic string descriptor. 


request 

VMS usage: identifier 

type: longword (unsigned) 
access: write only 


mechanism: by reference 


Code that identifies the request. The request argument is the address of a 
longword into which SMBSREAD_MESSAGE writes the code that identifies 
the request. 
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SMB$READ_MESSAGE 


There are seven request codes. Each code is interpreted as a message by the 
symbiont. The codes and their descriptions follow: 


SMBMSG$K_START_STREAM 


SMBMSG$K_STOP_STREAM 


SMBMSG$K_RESET_STREAM 


SMBMSG$K_START_TASK 


SMBMSG$K_STOP_TASK 


SMBMSG$K_PAUSE_TASK 


SMBMSG$K_RESUME_TASK 


Initiates processing on an inactive symbiont 
stream. The job controller sends this message 
when a START/QUEUE or an INITIALIZE 
/QUEUE/START command is issued on a 
stopped queue. 


Stops processing on a started queue. The job 
controller sends this message when a STOP 
/QUEUE/NEXT command is issued, after the 
symbiont completes any currently active task. 


Aborts all processing on a started stream and 
requeues the current job. The job controller 
sends this message when a STOP/QUEUE 
/RESET command is issued. 


‘Requests that the symbiont begin processing 


a task. The job controller sends this message 


_ when a file is pending on an idle, started 


queue. 


Requests that the symbiont abort the 
processing of a task. The job controller sends 
this message when a STOP/QUEVE/ABORT or 
STOP/QUEUVE/REQUEUE command is issued. 
The item SMBMSG$K_STOP_CONDITION 
identifies whether this is an abort or a requeue 
request. 


Requests that the symbiont pause in the 
processing of a task but retain the resources 
necessary to continue. The job controller 
sends this message when a STOP/QUEUE 
command is issued without the /ABORT, 
/ENTRY, /REQUEUE, or /NEXT qualifier for a 
queue that is currently printing a job. 


Requests that the symbiont continue 
processing a task that has been stopped 
with a PAUSE_TASK request. This message 
is sent when a START/QUEUE command is 
issued for a queue served by a symbiont that 
has paused in processing the current task. 





DESCRIPTION 


Your symbiont calls SMB$READ_-MESSAGE to read a message that the job 
controller has sent to the symbiont. 


Each message from the job controller consists of a code identifying the 
function the symbiont is to perform and a number of message items. There 
are seven codes. Message items are pieces of information that the symbiont 
needs to carry out the requested function. 
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For example, when you enter the DCL command PRINT, the job controller 
sends a message containing a START_TASK code and a message item 
containing the specification of the file to be printed. 


SMB$READ_MESSAGE writes the code into a longword (specified by the 
request argument) and writes the accompanying message items, if any, into a 
buffer (specified by the buffer argument). 


See the description of the SMBSREAD_MESSAGE_ITEM routine for 
information about processing the individual message items. 





CONDITION 
VALUES 
RETURNED 
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SS$_NORMAL Routine completed successfully. 


LIB$_INVARG Routine completed unsuccessfully because of an 
invalid argument. 


This routine also returns any of the condition codes returned by the Run-Time 
Library string-handling (STR$) routines. 
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SMB$READ_MESSAGE_ITEM 


SMBS$READ_MESSAGE_ITEM Parse Next Item 


from Message 
Buffer 


The SMB$READ_MESSAGE_ITEM routine reads a buffer that was filled in 
by the SMB$READ_MESSAGE routine, parses one message item from the 
buffer, writes the item’s code into a longword, and writes the item into a 
buffer. 





FORMAT 


SMBS$READ_MESSAGE_ITEM message ,context 
,Item_code ,buffer 
[size] 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


message 

VMS usage: char_string © 
type: character string 
access: read only 
mechanism: by descriptor 


Message items that SMB$READ_MESSAGE_ ITEM is to read. The message 
argument is the address of a descriptor of a buffer. The buffer is the one that 
contains the message items that SMB6READ_MESSAGE_ITEM is to read. 
The buffer specified here must be the same as that specified with the call to 
the SMB$READ_MESSAGE routine, which fills the buffer with the contents 
of the message. 


context 

VMS usage: context 

type: longword (unsigned) 
access: read only 


mechanism: by reference 


Value initalized to 0 specifying the first message item in the buffer to be read. 
The context argument is the address of a longword that the SMB$READ_ 
MESSAGE_ITEM routine uses to determine the next message item to be 
returned. When this value is 0, it indicates that SMB$READ_MESSAGE_ 
ITEM is to return the first message item. . 


The SMBSREAD_MESSAGE_ITEM routine updates this value each time it 
reads a message item. SMB$READ_MESSAGE_ITEM sets the value to 0 


when it has returned all the message items in the buffer. 
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item_code 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


Item code specified in the message item that identifies its type. The 
item_—code argument is the address of a longword into which 
SMB$READ_MESSAGE_ITEM writes the code that identifies what item it is 
returning. : 


The codes that identify message items are defined at the end of the 
Description section for this routine. 


The following diagram depicts the format of a single message item. 


31 15 





VARIABLE-LENGTH 
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SMB$READ_MESSAGE_ITEM copies the code from the second word in the 
message item to the longword specified by the item—code argument. 


SMB$READ_MESSAGE_ITEM uses the item-size field in the message item 
to determine the length, in bytes, of the variable-length message. 


buffer 

VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor 


Message item. The buffer argument is the address of a descriptor of a buffer. 
The buffer is the one in which the SMBSREAD_MESSAGE_ITEM routine 

is to place the message item. SMB$READ_MESSAGE-_ITEM uses the RTL 
STR§$ string-handling routines to copy the message item into the buffer. 


size 

VMS usage: word_unsigned 
type: word (unsigned) 
access: write only 


mechanism: by reference 


Size of the message item. The size argument is the address of a word in 
which the SMB$READ_MESSAGE_ ITEM is to place the size, in bytes, of the 
item. 
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DESCRIPTION 


The job controller can request seven functions from the symbiont. They are 
identified by the following codes: 


SMBMSG$K_START_STREAM SMBMSG$K_STOP_STREAM 
SMBMSG$K_START_TASK SMBMSG$K_PAUSE_TASK 
SMBMSG$K_RESUME_TASK SMBMSG$K_STOP_TASK 


SMBMSG$K_RESET_STREAM 


The job controller passes the symbiont a request containing a code and, 
optionally, a number of message items containing information the symbiont 
might need to perform the function. The code specifies what function the 
request is for, and the message items contain information that the symbiont 
needs to carry out the function. 


By calling SMB$READ_MESSAGE, the symbiont reads the request and writes 
the message items into the specified buffer. The symbiont then obtains 

the individual message items by calling the SMB6READ_MESSAGE_ITEM 
routine. 


Each message item consists of a code that identifies the information the item 
represents, and the item itself. For example, the SMB$K_JOB_NAME code 
tells the symbiont that the item specifies a job’s name. 


The number of items in a request varies with each type of request. Therefore, 
you must call SMB$READ_MESSAGE_ITEM repeatedly for each request to 
ensure that all message items are read. Each time SMBSREAD_MESSAGE_ 
ITEM reads a message item, it updates the value in the longword specified 
by the context argument. SMBSREAD_MESSAGE_ITEM returns the code 
SMB$_NOMOREITEMS after it has read the last message item. 


The following table shows the message items that can be delivered with each 
request. 


Request Message Item 


SMBMSG$K_START_TASK SMBMSG$K_ACCOUNT_NAME 
SMBMSG$K_AFTER_TIME 
SMBMSG$K_BOTTOM_MARGIN 
SMBMSG$K_CHARACTERISTICS 
SMBMSG$K_CHECKPOINT_DATA 
SMBMSG$K_ENTRY_NUMBER 
SMBMSG$K_FILE_COPIES 
SMBMSGS$K_FILE_COUNT 
SMBMSG$K _SETUP_MODULES 
SMBMSG$K_FIRST_PAGE 
SMBMSG$K_FORM_LENGTH 
SMBMSG$K__FORM_NAME 
SMBMSG$K__FORM__SETUP_MODULES 
SMBMSG$K_FORM_WIDTH 
SMBMSGS$K _FILE_IDENTIFICATION 
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Request Message Item 


SMBMSG$K_MESSAGE_VECTOR 
SMBMSG$K_FILE_SPECIFICATION 
SMBMSG$K_JOB_COPIES 
SMBMSG$K_JOB_COUNT 
SMBMSG$K_JOB_NAME 
SMBMSG$K_JOB_RESET_MODULES 
SMBMSG$K_LAST_PAGE 

SMBMSG$K _LEFT_MARGIN 
SMBMSG$K_NOTE 
SMBMSG$K_PAGE_SETUP_MODULES 
SMBMSG$K_PARAMETER_ 1 
SMBMSG$K_SEPARATION_CONTROL 
SMBMSG$K_REQUEST_CONTROL 
SMBMSG$K_PRIORITY 
SMBMSG$K_QUEUE 
SMBMSG$K_TIME_QUEUED 
SMBMSG$K_TOP_MARGIN 
SMBMSG$K_UIC 
SMBMSG$K_USER_NAME 
SMBMSG$K_RIGHT_MARGIN 


SMBMSG$K_STOP_TASK SMBMSG$K_STOP_CONDITION 
SMBMSG$K_PAUSE_TASK None 
SMBMSG$K_RESUME_TASK SMBMSG$K_ALIGNMENT_PAGES 


SMBMSG$K_RELATIVE_PAGE 
SMBMSG$K_REQUEST_CONTROL 
SMBMSG$K_SEARCH_STRING 


SMBMSG$K_START_STREAM SMBMSG$K_DEVICE_NAME 


SMBMSG$K_EXECUTOR_QUEUE 
SMBMSG$K_JOB_RESET_MODULES 
SMBMSG$K_LIBRARY_SPECIFICATION 


SMBMSG$K_STOP_STREAM None 
SMBMSG$K_.RESET_STREAM None 


Following are the message items that the symbiont can send to the job 
controller: 


SMBMSG$K_ACCOUNTING_DATA 
SMBMSG$K_CHECKPOINT_DATA 
SMBMSG$K_CONDITION_VECTOR 
SMBMSG$K_DEVICE_STATUS 
SMBMSG$K_REQUEST_RESPONSE 
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Note: 


SMB$READ_MESSAGE_ITEM 


The following list enumerates each item code. For each code, the list 
describes the contents of the message item identified by the code and whether 
the code identifies an item sent from the job controller to the symbiont or 
from the symbiont to the job controller. 


Many of the codes described are specifically oriented toward print symbionts. 
The symbiont you implement, which might not print files or serve an output 
device, need not recognize all these codes. In addition, it need not respond 
in the same way as the VMS print symbiont to the codes it recognizes. 

The descriptions in the list describe how the standard VMS print symbiont 
(PRTSMB.EXE) processes these items. 


Because new codes might be added in the future, you should write your 
symbiont so that it ignores codes it does not recognize. 


Codes for Message Items 


SMBMSGS$K_ACCOUNTING_DATA 


This code identifies a 16-byte structure that the symbiont sends to the job 
controller. This structure contains accounting statistics that the symbiont has 
accumulated for the task. The job controller accumulates task statistics into a 
job-accounting record, which it writes to the accounting file when the job is 
completed. 


The following diagram depicts the contents of the 16-byte structure. 


3 
1 0 
NUMBER OF PAGES PRINTED FOR THE JOB 
NUMBER OF READS FROM DISK 
NUMBER OF WRITES TO THE PRINTING DEVICE 
UNUSED 
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SMBMSG$K_ACCOUNT_NAME 


This code identifies a string containing the name of the account to be charged 
for the job, that is, the account of the process that submitted the print job. 
The job controller sends this item to the symbiont. 


SMBMSGS$K_AFTER_TIME 


This code identifies a 64-bit, absolute-time value specifying the system time 
after which the job controller can process this job. The job controller sends 
this item to the symbiont. 


SMBMSG$K_ALIGNMENT_PAGES 


This code identifies a longword specifying the number of alignment pages that 
the symbiont is to print. The job controller sends this item to the symbiont. 
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SMBMSG$K_BOTTOM_MARGIN 


This code identifies a longword containing the number of lines to be left 
blank at the bottom of a page. The job controller sends this item to the 
symbiont. 


The symbiont inserts a formfeed character into the output stream if it 
determines the following: 


e That the number of lines left at the bottom of the page is equal to the 
value in SMBMSG$K_BOTTOM_MARGIN 


e That sending more data to the printer to be output on this page would 
cause characters to be printed within this bottom margin of the page 


e That the /FEED qualifier was specified with the PRINT command that 
caused the symbiont to perform this task 


(Linefeed, formfeed, carriage-return, and vertical-tab characters in the output 
stream are collectively known as embedded carriage control.) 


SMBMSG$K_CHARACTERISTICS 


This code identifies a 32-byte structure specifying characteristics of the job. 

A detailed description of the format of this structure is contained in the 
description of the SJC$_CHARACTERISTIC code in the SYS$SNDJBC system 
service in the VMS System Services Reference Manual. The job controller sends 
this item to the symbiont. 


SMBMSG$K_CHECKPOINT_DATA 


This code identifies a user-defined structure containing checkpointing 
information. The symbiont sends this item to the job controller, which 
saves it in the queue’s data file. 


When a restart-from-checkpoint request is executed for the queue, the job 
controller retrieves the checkpointing information from the queue’s data file 
and sends it to the symbiont with a SMBMSG$K_START_TASK request. The 
symbiont uses the checkpointing information to reposition the input file to 
the point corresponding to the last page output at the time of the checkpoint. 


SMBMSG$K_CONDITION_VECTOR 


This code identifies an array of longwords, each longword containing a code 
that specifies a termination status for the current request. The symbiont sends 
this item to the job controller. For example, the STS and STV values from an 
RMS control block might be two longwords in the array. 


SMBMSG$K_DEVICE_NAME 


This code identifies a string that is the name of the device to which the 
symbiont is to send data. The symbiont interprets this information. The 
name need not be the name of a physical device, and the symbiont can 
interpret this string as something other than the name of a device. 


SMBMSGS$K_DEVICE_STATUS 

This code identifies a longword bit vector, each bit of which specifies device- 
status information. The symbiont sends this item to the job controller. The 
$SMBDEF macro defines these device-status bits. The following describes the 
effect of setting each bit in the longword. 
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Device Status Bit Description 
SMBMSG$V_LOWERCASE The device to which the symbiont is connected 


supports lowercase characters. 


SMBMSG$V_PAUSE_TASK Informs the job controller that the symbiont has 
paused on its own initiative. 


SMBMSG$V_REMOTE The device is connected to the symbiont by 
means of a modem. 

SMBMSG$V_SERVER The symbiont is not connected to a device. 

SMBMSG$V_STALLED Symbiont processing is temporarily stalled. 


SMBMSG$V_STOP_STREAM. ~— The symbiont requests that the job controller 
stop the queue. 


SMBMSG$\V_TERMINAL The symbiont is connected to a terminal. 


SMBMSG$V_UNAVAILABLE The device to which the symbiont is assigned is 


not available. 


SMBMSGSK_ENTRY_NUMBER 


This code identifies a longword containing the number that the job controller 
assigned to the job. The job controller sends this item to the symbiont. 


SMBMSG$K_EXECUTOR_QUEUE 


This code identifies a string that is the name of the queue on which the 
currently executing job is listed. The job controller sends this item to the 
symbiont. 


SMBMSG$K_FILE_COPIES 
This code identifies a longword containing the number of copies of the file 
that were requested. 


SMBMSGS$K_FILE_COUNT 


This code identifies a longword that specifies, out of the number of copies 
requested for this job (GMBMSG$K_FILE_COPIES), the number of the 
copy of the file currently printing. The job controller sends this item to the 
symbiont. 


SMBMSGS$K_FILE_IDENTIFICATION 


This code identifies a 28-byte structure identifying the file to be processed. 
This structure consists of the following three file-identification fields in the 
RMS NAM block: 


1 The 16-byte NAM$T_DVI field 
2 The 6-byte NAM$W_FID field 
3 The 6-byte NAM$W_DID field 


These fields occur consecutively in the NAM block in the order listed. The 
job controller sends this item to the symbiont. 
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SMBMSGS$K_FILE_SETUP_MODULES 


This code identifies a string specifying the names of one or more text modules 
that the symbiont should copy from the library into the output stream 
before processing the file. When you specify more than one name, you must 
separate the names with commas. The job controller sends this item to the 
symbiont. . 


SMBMSG$K_FILE_SPECIFICATION 


This code identifies a string specifying the name of the file that the symbiont 
is to process. This file name is formatted as a standard RMS file specification. 
The job controller sends this item to the symbiont. 


SMBMSG$K_FIRST_PAGE 


This code identifies a longword containing the number of the page at which 
the symbiont should begin printing. The job controller sends this item to the 
symbiont. When not specified, the symbiont begins processing at page 1. 


SMBMSG$K_FORM_LENGTH 


This code identifies a longword value specifying the length (in lines) of the 
physical form (the paper). The job controller sends this item to the symbiont. 


SMBMSG$K_FORM_NAME 


This code identifies a string specifying the name of the form. The job 
controller sends this item to the symbiont. 


SMBMSGS$K_FORM_SETUP_MODULES 


This code identifies a string consisting of the names of one or more modules 
that the symbiont should copy from the device-control library before 
processing the file. When you specify more than one name, you must 
separate the names with commas. The job controller sends this item to 

the symbiont. 


SMBMSG$K_FORM_WIDTH 


This code identifies a longword specifying the width (in characters) of the 
print area on the physical form (the paper). The symbiont sends this item to 
the job controller. 


SMBMSG$K_JOB_COPIES 


This code identifies a longword specifying the requested number of copies of 
the job. The job controller sends this item to the symbiont. 


SMBMSG$K_JOB_COUNT 


This code identifies a longword specifying, out of the number of copies 
requested (SMBMSG$K_JOB_COPIES), the number of the copy of the job 
currently printing. The job controller sends this item to the symbiont. 


SMBMSG$K_JOB_NAME 


This code identifies a string specifying the name of the job. The job controller 
sends this item to the symbiont. 
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SMBMSG$K_JOB_RESET_MODULES 


This code identifies a string specifying the names of one or more modules that 
the symbiont should copy from the device-control library after processing the 
task. These modules can be used to reset programmable devices to a known 
state. When you specify more than one name, you must separate the names 
with commas. The job controller sends this item to the symbiont. 


SMBMSG$K_LAST_PAGE 


This code identifies a longword specifying the number of the last page that 
the symbiont is to print. The job controller sends this item to the symbiont. 
When not specified, the symbiont attempts to print all the pages in the file. 


SMBMSGSK_LEFT_MARGIN 

This code identifies a longword specifying the number of spaces to be inserted 
at the beginning of each line. The job controller sends this item to the 
symbiont. 


SMBMSGSK_LIBRARY_SPECIFICATION 


This code identifies a string specifying the name of the device-control library. 
The job controller sends this item to the symbiont. 


SMBMSG$K_MESSAGE_VECTOR 


This code identifies a vector of longword condition codes, each of which 
contains information about the job to be printed. The job controller sends 
this item to the symbiont. 


When LOGINOUT cannot open a log file for a batch job, a code in the 
message vector specifies the reason for the failure. The job controller does 
not send the SMBMSG$K-_FILE_IDENTIFICATION item if it has detected 
such a failure but instead sends the message vector, which the symbiont 
prints, along with a message stating that there is no file to print. 


SMBMSG$K_NOTE 


This code identifies a user-supplied string that the symbiont is to print on the 
job-flag page and on the file-flag page. The job controller sends this item to 
the symbiont. 


SMBMSG$K_PAGE_SETUP_MODULES 


This code identifies a string consisting of the names of one or more modules 
that the symbiont should copy from the device-control library before printing 
each page. When you specify more than one name, you must separate the 
names with commas. The job controller sends this item to the symbiont. 


SMBMSG$K_PARAMETER _1 through 
SMBMSG$K_PARAMETER_8 

Each of these eight codes identifies a user-supplied string. Both the semantics 
and syntax of each string are determined by your symbiont. The VMS- 
supplied symbiont makes no use of these eight items. The job controller 
sends these items to the symbiont. 


SMBMSGS$K_PRINT_CONTROL 


This code identifies a longword bit vector, each bit of which supplies 
information that the symbiont is to use in controlling the printing of the 
file. The job controller sends this item to the symbiont. 
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The $SMBDEF macro defines the following symbols for each bit in the bit 


vector. 


Symbol 
SMBMSG$V_DOUBLE_SPACE 


SMBMSG$V_NORECORD_ 
BLOCKING 


SMBMSG$V_PAGE_HEADER 


SMBMSG$V_PAGINATE 


SMBMSG$V_PASSALL 


SMBMSG$V_RECORD_ 
BLOCKING 


SMBMSG$V_SEQUENCED 
SMBMSG$V_SHEET_FEED 
SMBMSG$V_TRUNCATE 


SMBMSG$V_WRAP 


SMBMSGS$K-_PRIORITY 


Description 


The symbiont uses a double-spaced format; it 
skips a line after each line it prints. 


The symbiont performs single record output, 
issuing a single output record for each input 
record. 


The symbiont prints a page header at the top of 
each page. 


The symbiont inserts a formfeed character 
when it detects an attempt to print in the 
bottom margin of the current form. 


The symbiont prints the file without formatting 
and bypasses all formatting normally performed. 
Furthermore, the symbiont outputs the file 
without formatting, by causing the output QIO 
to suppress formatting by the driver. 


The symbiont performs record blocking, 
buffering output to the device. 


This bit is reserved by DIGITAL. 
The symbiont pauses after each page it prints. 


The symbiont truncates input lines that exceed 
the right margin of the current form. 


The symbiont wraps input lines that exceed the 
right margin, printing the additional characters 
on a new line. 


This code identifies a longword specifying the priority this job has in the 
queue in which it is entered. The job controller sends this item to the 


symbiont. 


SMBMSGS$K_QUEUE 


This code identifies a string specifying the name of the queue in which this 
job is entered. The job controller sends this item to the symbiont. When 
generic queues are used, this item specifies the name of the generic queue, 
and the SMBMSG$K_EXECUTOR item specifies the name of the device 


queue or the server queue. 


SMBMSGS$K_RELATIVE_PAGE 


This code identifies a signed, longword value specifying the number of pages 
that the symbiont is to move forward (positive value) or backward (negative 
value) from the current position in the file. The job controller sends this item 
to the symbiont. 


SMBMSG$K_REQUEST_CONTROL 


This code identifies a longword bit vector each bit of which specifies 
information that the symbiont is to use in processing the request that the 
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job controller is making. The job controller sends this item to the symbiont. 
The $SMBDEF macro defines the following symbols for each bit. 


Symbol Description 


SMBMSG$V_ALIGNMENT_MASK _ The symbiont is to replace all alphabetic 
characters with the letter X, and all numeric 
characters with the number 9. Other 
characters (punctuation, carriage control, 
and so on) are left unchanged. This bit is 
ordinarily specified in connection with the 
SMBMSG$K_ALIGNMENT_PAGES item. 


SMBMSG$V_PAUSE_COMPLETE The symbiont is to pause when it completes 
the current request. 


SMBMSG$V_RESTARTING Indicates that this job was previously 
interrupted and requeued, and is now 
restarting. 

SMBMSG$V_TOP_OF_FILE The symbiont is to rewind the input file 


before it resumes printing. 


SMBMSGS$K_REQUEST_RESPONSE 


This code identifies a longword specifying the type of request for which the 
symbiont is currently signalling completion. The symbiont sends this item to 
the job controller. The following symbols define types of requests you can 
specify in this item: 


SMBMSG$K_START_STREAM SMBMSG$K_STOP_STREAM 
SMBMSG$K_START_TASK SMBMSG$K_PAUSE_TASK 
SMBMSG$K_RESUME_TASK SMBMSG$K_STOP_TASK 
SMBMSG$K_RESET_STREAM SMBMSG$K__COMPLETE_TASK 


SMBMSG$K_TASK_STATUS 


SMBMSG$K_RIGHT_MARGIN 


This code identifies a longword specifying the number of character positions 
to be left empty at the end of each line. The job controller sends this item to 
the symbiont. When the right margin is exceeded, the symbiont truncates the 
line, wraps the line, or continues processing, depending on the settings of the 
WRAP and TRUNCATE bits in the SMBMSG$K_PRINT_CONTROL item. 


SMBMSG$K_SEARCH_STRING 

This code identifies a string containing the value specified in the START 
/QUEUE/SEARCH command. The job controller sends this item to the 
symbiont. This string identifies the page at which to restart the current 
printing task on a paused queue. 


SMBMSG$K_SEPARATION_CONTROL 

This code identifies a longword bit vector, each bit of which specifies an 
operation that the symbiont is to perform between jobs or between files 
within a job. The job controller sends this item to the symbiont. The 
$SMBDEF macro defines the following symbols for each bit. 
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Symbol 
SMBMSG$V_FILE_BURST 


SMBMSG$V_FILE_FLAG 
SMBMSG$V_FILE_TRAILER 


SMBMSG$V_FILE_TRAILER_ABORT 


SMBMSG$V_FIRST_FILE_OF_JOB 


SMBMSG$V_JOB_FLAG 


SMBMSG$V_JOB_BURST 


SMBMSG$V_JOB_RESET 


SMBMSG$V_JOB_RESET_ABORT 


SMBMSG$V_JOB_TRAILER 


SMBMSG$V_JOB_TRAILER_ABORT 


SMBMSG$V_LAST_FILE_OF_JOB 


Description 


The symbiont is to print a file-burst 
page. 
The symbiont is to print a file-flag page. 


The symbiont is to print a file-trailer 
page. 

The symbiont is to print a file- 
trailer page when a task completes 
abnormally. 


The current file is the first file of the 
job. When specified with SMBMSG$V_ 
LAST_FILE_OF_JOB, the current job 
contains a single file. 


The symbiont is to print a job-flag 
page. 

The symbiont is to print a job-burst 
page. 

The symbiont is to execute a job-reset 
sequence when the task completes. 
The symbiont is to execute a job- 
reset sequence when a task completes 
abnormally. 

The symbiont is to print a job-trailer 
page. 

The symbiont is to print a job- 

trailer page when a task completes 
abnormally. 


The current file is the last file of the 
job. When specified with SMBMSG$V_. 
FIRST_FILE_OF_JOB, the current job 
contains a single job. 


SMBMSG$K_STOP_CONDITION 


This code identifies a longword containing a condition specifying the reason 
the job controller issued a STOP_TASK request. The job controller sends this 
item to the symbiont. 


SMBMSG$K_TIME_QUEUED 


This code identifies a quadword specifying the time the file was entered into 
the queue. The time is expressed as 64-bit, absolute time. The job controller 
sends this item to the symbiont. 


SMBMSG$K_TOP_MARGIN 


This code identifies a longword specifying the number of lines that the 
symbiont is to leave blank at the top of each page. PRTSMB inserts linefeeds 
into the output stream after every formfeed until the margin is cleared. 


SMBMSG$K_UVIC 


This code identifies a longword specifying the User Identification Code (UIC) 
of the user who submitted the job. 
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SMBMSG$K_USER_NAME 
This code identifies a string specifying the name of the user who submitted 





the job. 
CONDITION = ae 
VALUES pe eas ieee sa: ete i ully. 
RETURNED — nd of item list reached. 


This routine also returns any condition code returned by the Run-Time 
Library string-handling (STR$) routines. 
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SMBS$SEND_TO_JOBCTL Send Message to Job 
Controller 


The SMB$SEND_.TO_JOBCTL routine is used by your symbiont to send 
messages to the job controller. Three types of message can be sent: 
request-completion messages, task-completion messages, and task-status 








messages. 
FORMAT SMB$SEND_TO_JOBCTL stream [, request] 
[,accounting] [, checkpoint] 
_ [,device_status] [, error] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS __ stream 
VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Stream number specifying the stream to which the message refers. The 
stream argument is the address of a longword containing the number of the 
stream to which the message refers. 


request 

VMS usage: identifier 

type: longword (unsigned) 
access: read only 


mechanism: by reference 


Request code identifying the request being completed. The request argument 
is the address of a longword containing the code that identifies the request 
that has been completed. 


The code usually corresponds to the code the job controller passed to the 
symbiont by means of a call to SMBS6READ_MESSAGE. But the symbiont 
can also initiate task-completion and task-status messages that are not in 
response to a request. (See the DESCRIPTION section.) 
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accounting 

VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor 


Accounting information about a task. The accounting argument is the address 
of a descriptor pointing to the accounting information about a task. Note that 
this structure is passed by descriptor and not by reference. 


See the description of the SMBMSG$K_ACCOUNTING_DATA item for 
more information about this accounting information. 


The following diagram depicts the contents of the 16-byte structure. 


3 
1 0 
NUMBER OF PAGES PRINTED FOR THE JOB 
NUMBER OF READS FROM DISK OR TAPE 
NUMBER OF WRITES TO THE PRINTING DEVICE 
UNUSED 






ZK-2012-84 
checkpoint ; 
VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor 


Checkpoint data about the currently executing task. The checkpoint 
argument is the address of the descriptor that points to checkpointing 
information that relates to the status of a task. When the symbiont sends 
this information to the job controller, the job controller saves it in the queue’s 
data file. When a restart-from-checkpoint request is executed for the queue, 
the job controller retrieves the checkpointing information from the queue’s 
data file and sends it to the symbiont in the SMBMSG$K—CHECKPOINT_ 
DATA item that accompanies a SMBMSG$K_START_TASK request. 


Print symbionts can use the checkpointing information to reposition the 
input file to the point corresponding to the page being output when the last 
checkpoint was taken. Other symbionts might use checkpoint information to 
specify restart information for partially completed tasks. 


Because each checkpoint causes information to be written into the 

job controller's queue-data file, taking a checkpoint incurs significant 
overhead. Use caution in regard to the size and frequency of checkpoints. 
When determining how often to checkpoint, weigh processor and file- 
system overhead against the convenience of restarting. 
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device_status 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Status of the device served by the symbiont. The device_status argument 
is the address of a longword passed to the job controller, which contains the 
status of the device to which the symbiont is connected. 


This longword contains a longword bit vector, each bit of which specifies 
device-status information. The $SMBDEF macro defines these device-status 
bits. The following table describes each bit. 


Device Status Bit Description 


SMBMSG$V_LOWERCASE The device to which the symbiont is connected 
supports lowercase characters. 


SMBMSG$V_PAUSE_TASK The symbiont sends this message to inform the 
job controller that the symbiont has paused on 
its own initiative. 


SMBMSG$V_REMOTE The device is connected to the symbiont by 
means of a modem. 

SMBMSG$V_SERVER The symbiont is not connected to a device. 

SMBMSG$V_STALLED Symbiont processing is temporarily stalled. 


SMBMSG$V_STOP_STREAM The symbiont requests that the job controller 
stop the queue. 


SMBMSG$V_TERMINAL The symbiont is connected to a terminal. 


SMBMSG$V_UNAVAILABLE The device to which the symbiont is connected 
is not available. 


error 

VMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Condition codes returned by the requested task. The error argument is the 
address of a vector of longword condition codes. The first longword contains 
the number of longwords following it. 


If the low bit of the first condition code is clear, the job controller aborts 
further processing of the job. Output of any remaining files, copies of files, or 
copies of the job is canceled. In addition, the job controller saves up to three 
condition values in the queue’s data file. The first condition value is included 
in the job-accounting record that is written to the system’s accounting file 
(SYSSMANAGER:ACCOUNTNG.DAT). 
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DESCRIPTION 


The symbiont uses the SMB$SEND_TO_JOBCTL routine to send messages 
to the job controller. 


Most messages the symbiont sends to the job controller are responses to 
requests made by the job controller. These responses inform the job controller 
that the request has been completed, either successfully or with an error. 
When the symbiont sends the message, it usually indicates that the request 
has been completed. 


In such messages, the request argument corresponds to the function code 

of the request that has been completed. Thus, if the job controller sends a 
request using the SMBMSG$K_START_TASK code, the symbiont responds 
by sending a SMB$SEND_TO_JOBCTL message using SMBMSG$K_START_ 
TASK as the request argument. 


The responses to some requests use additional arguments to send more 
information in addition to the request code. The following table shows which 
additional arguments are allowed in response to each different request. 


Request Arguments 


SMBMSG$K_START_STREAM _ request 
device_status 
error 

SMBMSG$K_STOP_STREAM request 

SMBMSG$K_RESET_STREAM request 


SMBMSG$K_START_TASK request 
SMBMSG$K_PAUSE_TASK request 
SMBMSG$K_RESUME_TASK request 
SMBMSG$K_STOP_TASK request 
error’ 


'This is usually the value specified in the SMBMSG$K_STOP_CONDITION item that was 
sent by the job controller with the SMBMSG$K_STOP_TASK request. 


In addition to responding to requests from the job controller, the symbiont 
can send other messages to the job controller. If the symbiont sends a 
message that is not a response to a request, it uses either the SMBMSG$K_ 
TASK—COMPLETE or SMBMSG$K_TASK_STATUS code. Following are the 
additional arguments that you can use with the messages identified by these 
codes. 


Code Arguments 


SMBMSG$K__TASK_COMPLETE request 
accounting 
error 

SMBMSG$K_TASK_STATUS request 
checkpoint 
device_status 


SMB-37 


Symbiont/Job Controller Interface ome) Routines 
SMB$SEND_TO_JOBCTL 


The symbiont uses the SMB$K_TASK_STATUS message to update the job 
controller on the status of a task during the processing of that task. The 
checkpoint information passed to the job controller with this message permits 
the job controller to restart an interrupted task from an appropriate point. 
The device-status information permits the symbiont to report changes in 
device’s status (device stalled, for example). 


The symbiont can use the SMB$K_TASK_STATUS message to request that 
the job controller send a stop-stream request. It does this by setting the 
stop-stream bit in the device-status argument. 


The symbiont can also use the SMB$K_TASK_STATUS message to notify 
the job controller that the symbiont has paused in processing a task. It does 
so by setting the pause-task bit in the device-status argument. 


The symbiont uses the SMB$K_TASK_COMPLETE message to signal the 
completion of a task. Note that, when the symbiont receives a START_TASK 
request, it responds by sending a SMB$SEND_TO_JOBCTL message with 
SMBSMG$K_START_TASK as the request argument. This response means 


- that the symbiont has started the task; it does not mean the task has been 


completed. When the symbiont has completed a task, it sends a SMB$SEND_ 
TO_JOBCTL message with SMBSMG$K_TASK_COMPLETE as the request 
argument. 


Optionally, the symbiont can specify accounting information when sending a 
task-completion message. The accounting statistics accumulate to give a total 
for the job when the job is completed. 


Also, if the symbiont is aborting the task because of a symbiont-detected 
error, you can specify up to three condition values in the error argument. 
Aborting a task causes the remainder of the job to be aborted. 





CONDITION 
VALUES 
RETURNED 
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SS$_NORMAL Routine completed successfully. 


This routine also returns any condition value returned by the $QIO system 
service and the LIB$GET_VM routine. 


1 2 Sort/Merge (SOR) Routines 


12.1 





Introduction to SOR Routines 


Note: 


The SOR routines allow you to integrate a sort or merge operation into a 
program application. Using these callable routines, you can process some 
records, sort or merge them, and then process them again. 


The following SOR routines are available for use in a sort or merge operation: 


SOR$BEGIN_MERGE Sets up key arguments and performs the merge. This is 
the only routine unique to MERGE. 


SOR$BEGIN_SORT Initializes sort operation by passing key information and 
sort options. This is the only routine unique to SORT. 
SOR$DTYPE Defines a key data-type that is not normally supported 
by SORT/MERGE. 
SORSEND_SORT Performs cleanup functions, such as closing files and 
releasing memory. 
SOR$PASS_FILES Passes names of input and output files to SORT or 


MERGE; must be repeated for each input file. 


SOR$RELEASE_REC Passes one input record to SORT or MERGE; must be 
called once for each record. 


SORSRETURN_REC Returns one sorted or merged record to a program; 
must be called once for each record. 


SOR$SORT_MERGE Sorts the records. 


SOR$SPEC_FILE Passes a specification file or specification text. A call 
to this routine must precede all other calls to the SOR 
routines. 

SORSSTAT Returns a Statistic about the sort or merge operation. 


You can still call SOR$DO_MERGE (from VMS Version 3.0) as the 
equivalent of SORSEND_SORT; you can still call SOR$INIT_MERGE 
and SOR$INIT_SORT (from VMS Version 3.0) as the equivalent of 
SOR$BEGIN_SORT and SOR$BEGIN—_MERGE. However, for any new 
programs that you are creating, you are advised to use SORSEND_-SORT, 
SOR$BEGIN_SORT, and SOR$BEGIN_MERGE. 


You can call these SOR routines from any language that supports the VAX 
Procedure Calling and Condition Handling Standard. 


After being called, each of these routines performs its function and returns 
control to a program. It also returns a 32-bit condition code value indicating 
success or error, which a program can test to determine success or failure 
conditions. 
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12.1.1 Arguments to SOR Routines 


For a sort operation, the arguments to the SOR routines provide SORT with 
file specifications, key information, and instructions about the sorting process. 
For a merge operation, the arguments to the SOR routines provide MERGE 
with the number of input files, input and output file specifications, record 
information, key information, and input routine information. 


There are both mandatory and optional arguments. The mandatory 
arguments appear first in the argument list. You must specify all arguments 
in the order in which they are positioned in the argument list, separating each 
with a comma. Pass a zero by value to specify any optional arguments that 
you are omitting from within the list. You can end the argument list any time 
after specifying all the mandatory and desired optional arguments. 


12.1.2 Interfaces to SOR Routines 
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12.1.2.1 


You can submit data to the SOR routines as complete files or as single records. 
When your program submits one or more files to SORT or MERGE, which 
then creates one sorted or merged output file, you are using the file interface. 
When your program submits records one at a time and then receives the 
ordered records one at a time, you are using the record interface. 


You can combine the file interface with the record interface by submitting files 
on input and receiving the ordered records on output, or by releasing records 
on input and writing the ordered records to a file on output. Combining 

the two interfaces provides greater flexibility. If you use the record interface 
on input, you can process the records before they are sorted; if you use the 
record interface on output, you can process the records after they are sorted. 


The SOR routines used and the order in which they are called depend on 
the type of interface used in a sorting or merging operation. The following 
sections detail the calling sequence for each of the interfaces. Note, however, 
that if you use the SOR$STAT routine, it must be called before any other SOR 
routine. 


Sort Operation Using File Interface 

For a sort operation using the file interface, pass the input and output 

file specifications to SORT by calling SOR$PASS_FILES. You must call 
SOR$PASS_FILES for each input file specification. Pass the output file 
specification in the first call. If no input files are specified before the call to 
SOR$BEGIN_SORT, the record interface is used for input; if no output file is 
specified, the record interface is used for output. 


Next, call SOR$BEGIN—SORT to pass instructions about keys and sort 
options. At this point, you must indicate if you want to use your own key 
comparison routine. SORT automatically generates a key comparison routine 
that is efficient for key data types; however, you may want to provide your 
own comparison routine to handle special sorting requirements. (For example, 
you may want names beginning with “Mc” and “Mac” to be placed together.) 
If you use your own key comparison routine, you must pass its address with 
the user_compare argument. 


Call SOR$SORT_MERGE to execute the sort and direct the sorted records 
to the output file. Finally, call SOR6END_SORT to end the sort and release 
resources. The SORS$END_SORT routine may be called at any time to abort 
a sort, or to merge and release all resources allocated to the sort or merge 
process. 


12.1.2.2 


12.1.2.3 


12.1.2.4 


12.1.3 Reentrancy 
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Sort Operation Using Record Interface 

For a sort operation using the record interface, first call SORSBEGIN—SORT. 
As in the file interface, this routine sets up work areas and passes arguments 
that define keys and sort options. Note that, if you use the record interface, 
you must use a record-sorting process (not a tag, address, or index process). 


Next, call SOR$RELEASE_REC to release a record to SORT. Call 
SOR$RELEASE_REC once for each record to be released. After all records 
have been passed to SORT, call SORSSORT_MERGE to perform the sorting. 


After the sort has been performed, call SORS$RETURN_REC to return a 
record from the sort operation. Call this routine once for each record to be 
returned. Finally, call the last routine, SORS$END_SORT, to complete the sort 
operation and release resources. 


Merge Operation Using File Interface 

For a merge operation using the file interface, pass the input and output file 
specifications to MERGE by calling SOR$PASS_FILES. You can merge up to 
10 input files by calling SOR$PASS_FILES once for each file. Pass the file 
specification for the merged output file in the first call. If no input files are 
specified before the call to SOR$5BEGIN—_MERGE, the record interface is used 
for input; if no output file is specified, the record interface is used for output. 


Next, to execute the merge, call SOR$BEGIN_MERGE to pass key 
information and merge options. At this point, you must indicate if you 
want to use your own key comparison routine tailored to your data. Finally, 
call SORS$END_SORT to release resources. 


Merge Operation Using Record Interface : 

For a merge operation using the record interface, first call SORS$BEGIN— 
MERGE. As in the file interface, this routine passes arguments that define 
keys and merge options. It also issues the first call to the input routine, which 
you must create, to begin releasing records to the merge. 


Next, call SORSRETURN_REC to return the merged records to your 
program. You must call this routine once for each record to be returned. 
SOR$RETURN_REC continues to call the input routine. MERGE, unlike 
SORT, does not need to hold all the records before it can begin returning 
them in the desired order. The releasing, merging, and returning of records 
all take place in this phase of the merge. 


Finally, after all the records have been returned, call the last routine, 
SOR$SEND_SORT, to clean up and release resources. 


The SOR routines are reentrant; that is, a number of sort or merge operations 
can be active at the same time. Thus, a program does not need to finish one 
sort or merge operation before beginning another. For example, reentrancy 
allows. you to perform multiple sorts on a file such as a mailing list and to 
create several output files, one with the records sorted by name, another 
sorted by state, another sorted by zip code, and so on. 


The context argument, which may optionally be passed with any of the SOR 
routines, distinguishes among multiple sort or merge operations. When using 
multiple sort or merge operations, the context argument is required. On the 
first call, the context longword must be zero. It is then set (by 
SORT/MERGE) to a value identifying the sort or merge operation. Additional 
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calls to the same sort or merge operation must pass the same context 
longword. The SOR$END_SORT routine clears the context longword. 


12.2 Examples of Using SOR Routines 


Example 12-1 is a VAX FORTRAN program demonstrating a merge operation 
using a record interface. 





Example 12—1 Using SOR Routines to Perform a Merge Using Record Interface in a VAX 
FORTRAN Program 





FORTRAN Program 
This program demonstrates the FORTRAN calling sequences 
for the merge record interface. 
THE INPUT FILES ARE LISTED BELOW. 
INFILE1 .DAT 


1 BBBBBBBBBB REST OF DATA IN RECORD............... cee eee eee eee END OF RECORD 
2 UUUUUUUUUU REST OF DATA IN RECORD..........................0.008.0, END OF RECORD 


INFILE2.DAT 


1 AAAAAAAAAA REST OF DATA IN RECORD........... 0... cece eee eee eee END OF RECORD 
2 TITTTTTTTT REST OF DATA IN RECORD............. 0.0... cece eee ee eee END OF RECORD 


INFILE3 . DAT 


ft TITTITITIT REST. OF DATA: IN. RECORD e052 oa. 5 ces ciaces ee igs Seewe END OF RECORD 
2 BBBBBBBBBB REST OF DATA IN RECORD............... 0c cece eee eee END OF RECORD 
FOROUT . DAT 

1 AAAAAAAAAA REST OF DATA IN RECORD............ 0... ec eee eee eee END OF RECORD 
1 BBBBBBBBBB REST OF DATA IN RECORD............. cc eee cece ee eee END OF RECORD 
1 TTTTTITTTTT REST OF DATA IN RECORD........... ccc eee ee eee eee END OF RECORD 
2 BBBBBBBBBB REST OF DATA IN RECORD.............. cece eee ee eee END OF RECORD 
Z. TITTITITIT REST OF DATA. IN RECORD. 3) sys aus: eo eaie-a gm gsntee hele denice ules! 6 END OF RECORD 
2 


UUUUUUUUUU REST OF DATA IN RECORD................ Lak tod obseniee @ iva ath ire END OF RECORD 


SS 2 


AAAQARAAAAQAAARQRAQAAAAAAAAAQARQAAAQAAARQAAARAAARQAAAARAARAANA 


Example 12—1 Cont'd. on next page 
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Example 12—1 (Cont.) Using SOR Routines to Perform a Merge Using Record Interface in 


aQqaa 


qaqa 


Qaqaqaagn 


Aaaqaa 


200 


aQaana 


a VAX FORTRAN Program 


IMPLICIT INTEGER (A-Z) 


CHARACTER*80 REC ! A record. 

EXTERNAL READ_REC ! Routine to read a record. 
EXTERNAL KOMPAR ! Routine to compare records. 
EXTERNAL SS$_ENDOFFILE ! System end-of-file value 
INTEGER*4 SOR$BEGIN_MERGE ! SORT/MERGE function names 


INTEGER*4 SOR$RETURN_REC 
INTEGER*4 SOR$END_SORT 


INTEGER*4 ISTAT ! storage for SORT/MERGE function value 
INTEGER*4 LENGTH ! length of the returned record 
INTEGER*2 LRL ! Longest Record Length (LRL) 

LOGICAL*1 ORDER ! #files to merge (merge order) 

DATA ORDER, LRL/3,80/ ! Order of the merge=3,LRL=80 


First open all the input files. 


OPEN (UNIT=10, FILE='INFILE1.DAT' ,TYPE='OLD' , READONLY, 
FORM='FORMATTED' ) 

OPEN (UNIT=11, FILE='INFILE2.DAT',TYPE='OLD' , READONLY, 
FORM=' FORMATTED ' ) 

OPEN (UNIT=12, FILE='INFILE3.DAT' , TYPE='OLD' , READONLY, 
FORM=' FORMATTED ' ) 


Open the output file. 

OPEN (UNIT=8, FILE='TEMP.TMP', TYPE='NEW') 

Initialize the merge. Pass the merge order, the largest 
record length, the compare routine address, and the 
input routine address. 

ISTAT = SOR$BEGIN_MERGE (,LRL, ,ORDER, 


KOMPAR, , READ_REC) 
IF (.NOT. ISTAT) GOTO 10 ! Check for error. 


Now loop getting merged records. SOR$RETURN_REC will 
call READ_REC when it needs input. 


ISTAT = SOR$RETURN_REC (REC, LENGTH) 


IF (ISTAT .EQ. %LOC(SS$_ENDOFFILE)) GO TO 30 ! Check for end of file. 
IF (.NOT. ISTAT) GO TO 10 ! Check for error. 

WRITE(8,200) REC ! Output the record. 

FORMAT(' ',A) 

GOTO 5 ! And loop back. 


Now tell SORT that we are all done. 


ISTAT = SOR$END_SORT() 
IF (.NOT. ISTAT) GOTO 10 ! Check for error. 
CALL EXIT 


Example 12—1 Cont'd. on next page 
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Example 12—1 (Cont.) Using SOR Routines to Perform a Merge Using Record Interface in 


a VAX FORTRAN Program 





QaQaQQnQ 


201 


AAQAQAQANQARQAARANRQAARAAARAARAARAN 


100 


Here if an error occurred. Write out the error status 
and exit. 


WRITE(8, 201) ISTAT 

FORMAT(' ?ERROR CODE', 120) 
CALL EXIT 

END 


FUNCTION READ_REC (RECX, FILE, SIZE) 


This routine reads a record from one of the input files 
for merging. It will be called by SOR$BEGIN_MERGE and by 
SOR$RETURN_REC . 


Parameters: 

RECX.wcp.ds character buffer to hold the record after 
it is read in. 

FILE.rl.r indicates which file the record is 
to be read from. 1 specifies the 
first file, 2 specifies the second 
etc. 

LENGTH .wl.r is the actual number of bytes in 


the record. This is set by READ_REC. 


IMPLICIT INTEGER (A-Z) 


PARAMETER MAXFIL=10 ! Max number of files. 
EXTERNAL SS$_ENDOFFILE ! End of file status code. 
EXTERNAL SS$_NORMAL ! Success status code. 
LOGICAL*1 FILTAB(MAXFIL) 

CHARACTER* (80) RECX ! MAX LRL =80 

DATA FILTAB/10,11,12,13,14,15,16,17,18,19/ ! Table of I/O unit numbers. 
READ_REC = %LOC(SS$_ENDOFFILE) ! Give end of file return 

IF (FILE .LT. 1 .OR. FILE .GT. MAXFIL) RETURN { if illegal call. 
READ (FILTAB(FILE), 100, ERR=75, END=50) RECX ! Read the record. 
FORMAT (A) 

READ_REC = %LOC(SS$_NORMAL) ! Return success code. 

SIZE = LEN (RECX) ! Return size of record. 
RETURN 

Here if end of file. 

READ_REC = %LOC(SS$_ENDOFFILE) ! Return "end of file" code. 
RETURN 

Here if error while reading 

READ_REC = 0 

SIZE = 0 

RETURN 

END 


Example 12—1 Cont'd. on next page 
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Example 12—1 (Cont.) Using SOR Routines to Perform a Merge Using Record Interface in 
a VAX FORTRAN Program 


FUNCTION KOMPAR (REC1,REC2) 


This routine compares two records. It returns -1 

if the first record is smaller than the second, 

0 if the records are equal, and 1 if the first record 
is larger than the second. 


ARQQaAaAQ 


PARAMETER KEYSIZ=10 
IMPLICIT INTEGER (A-Z) 
LOGICAL*1 REC1(KEYSIZ) , REC2(KEYSIZ) 


DO 20 I=1,KEYSIZ 

KOMPAR = REC1(I) - REC2(I) 

IF (KOMPAR .NE. 0) GOTO 50 
20 CONTINUE 


RETURN 


50 KOMPAR = ISIGN (1, KOMPAR) 
RETURN 
END 


Example 12-2 is a VAX FORTRAN program demonstrating a sort operation 
using a file interface on input and a record interface on output. 


Example 12—2 Using SOR Routines to Sort Using Mixed Interface in a VAX FORTRAN 
Program 


Program 


PROGRAM CALLSORT 


This is a sample FORTRAN program that calls the SOR 
routines using the file interface for input and the 
record interface for output. This program requests 
a record sort of the file 'RO10SQ.DAT' and writes 
the records to SYS$OUTPUT. The key is an 80-byte 
character ascending key starting in position 1 of 
each record. 


A short version of the input and output files follows: 


Input file RO10SQ. DAT 


1 BBBBBBBBBB REST OF DATA IN RECORD............ 0... e cece eee eee END OF RECORD 
2 UUUUUUUUUU REST OF DATA IN RECORD................ cece eee eee eee END OF RECORD 
1 AAAAAAAAAA REST OF DATA IN RECORD.............. 0. eee eee eee END OF RECORD 
2 2201 TEE REST OF DATA. IN RECORD 2,2. 24s tec cela tabs teed ee 2 ak es END OF RECORD 
1 TITTTTTTTT REST OF DATA IN RECORD....... voted take Wire traats ates END OF RECORD 
2 BBBBBBBBBB REST OF DATA IN RECORD.............. 0. cece eee ee eee END OF RECORD 
1 QQQQQQQQQQ REST OF DATA IN RECORD................. 0... cee ee eee END OF RECORD 
2 AAAAAAAAAA REST OF DATA IN RECORD............. 00... cee e ee eee END OF RECORD 
1 UUUUUUUUUU REST OF DATA IN RECORD.............. cee eee eee END OF RECORD 
2 QQQQQQQQQQ REST OF DATA IN RECORD............. 0.0.0.0... eee eee eee END OF RECORD 


QAQAQAAQRAAARAARQAARQAaRAaRAaAAaARQAaAaAaAaRAQ 


Example 12—2 Cont'd. on next page 
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Example 12-2 (Cont.) Using SOR Routines to Sort Using Mixed Interface in a VAX 
FORTRAN Program 





Output file SYS$OUTPUT 


AAAAAAAAAA REST OF DATA IN RECORD............ 0.0... c cece eee eee END OF RECORD 
BBBBBBBBBB REST OF DATA IN RECORD............ 0c cece eee eee END OF RECORD 
QQQQQQQQQQ REST OF DATA IN RECORD............. cee cece eee eee END OF RECORD 
TIITITTITT REST OF DATA. IN RECORD. 6.9 ser ig ca hb YS ees oO SENOS Lee Se END OF RECORD 
UUUUUUUUUU REST OF DATA IN RECORD............. ccc eee eee eee END OF RECORD 
AAAAAAAAAA REST OF DATA IN RECORD... ........ 0c cee cee cece nee eens END OF RECORD 
BBBBBBBBBB REST OF DATA IN RECORD......... 0... eee eee eee eee END OF RECORD 
QQQQQQAQQQ REST OF DATA IN RECORD...... 0... 0... cece eee END OF RECORD 
TITTTITTTT REST OF DATA IN RECORD. .... 0... ccc ec eee tee eee ees END OF RECORD 
UUUUUUUUUU REST OF DATA IN RECORD............ cece eee eee ees END OF RECORD 


DONMODNONNF RP Fe 


ew we we we wn a a a ew ee ew we ww ew ew mm em em me a ew mm em em ee ew ee ee ewe ee ee 


Define external functions and data. 


ARAQRQAAARNRQAAQARAARARQANA 


CHARACTER*80 RECBUF 

CHARACTER*10 INPUTNAME !Input file name 
INTEGER*2 KEYBUF (5) 'Key definition buffer 
INTEGER*4 SOR$PASS_FILES !SORT function names 
INTEGER*4 SOR$BEGIN_SORT 

INTEGER*4 SOR$SORT_MERGE 

INTEGER*4 SOR$RETURN_REC 

INTEGER*4 SOR$END_SORT 

INTEGER*4 ISTATUS !Storage for SORT function value 
EXTERNAL SS$_ENDOFFILE 

EXTERNAL DSC$K_DTYPE_T 

EXTERNAL SOR$GK_RECORD 

INTEGER*4 SRTITYPE 


Initialize data -- first the file names, then the key buffer for 
one 80-byte character key starting in position 1, 3 work files, 
and a record sort process. 


AaAQaaa 


DATA INPUTNAME/'RO10SQ.DAT'/ 
KEYBUF(1) = 1 

KEYBUF (2) = %LOC(DSC$K_DTYPE_T) 
KEYBUF (3) = 0 

KEYBUF (4) = 0 

KEYBUF (5) = 80 

SRITYPE = %LOC (SOR$GK_RECORD) 


Call the SORT -- each call is a function. 


Pass SORT the file names. 


QAaaaaa 


ISTATUS = SOR$PASS_FILES (INPUTNAME) 
IF (.NOT. ISTATUS) GOTO 10 


Initialize the work areas and keys. 


Qaa 


ISTATUS = SOR$BEGIN_SORT(KEYBUF,,,,,,SRTTYPE, (REF (3) ) 
IF (.NOT. ISTATUS) GOTO 10 





Example 12—2 Cont'd. on next page 
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Example 12—2 (Cont.) Using SOR Routines to Sort Using Mixed Interface in a VAX 
FORTRAN Program 


Sort the records. 


Q2aa 


ISTATUS = SOR$SORT_MERGE( ) 
IF (.NOT. ISTATUS) GOTO 10 


Now retrieve the individual records and display them. 


OaQana 


ISTATUS = SOR$RETURN_REC (RECBUF) 

IF (.NOT. ISTATUS) GOTO 6 

ISTATUS = LIB$PUT_OUTPUT (RECBUF) 

GOTO 5 

IF (ISTATUS .EQ. %LOC(SS$_ENDOFFILE)) GOTO 7 
GOTO 10 


o>) 


Clean up the work areas and files. 


SNOQQA 


ISTATUS = SOR$END_SORT() 
IF (.NOT. ISTATUS) GOTO 10 
STOP ‘SORT SUCCESSFUL' 

10 STOP 'SORT UNSUCCESSFUL ' 
END 





Example 12-3 is a VAX Pascal program demonstrating a merge operation 
using a file interface. 


Example 12—3 Using SOR Routines to Merge Three Input Files in a 
VAX Pascal Program 





Program 


(* This program merges three input files, (IN_FILE.DAT, 
IN_FILE2.DAT IN_FILE3.DAT), and creates one merged output file. *) 


program mergerecs( output, in_file1, in_file2, in_file3, out_file ); 


CONST 
SS$_NORMAL = 1; 
SS$_ENDOFFILE = %X870; 
SOR$GK_RECORD = 1; 
SOR$M_STABLE = 1; 
SOR$M_SEQ_CHECK = 4; 
SOR$M_SIGNAL = 8; 
DSC$K_DTYPE_T = 14; 


TYPE 
$UBYTE = [BYTE] 0..255; 
$UWORD = [WORD] 0. .65535; 
const 


num_of_keys 


merge_order = 3; 
1rl = 131; 
ascending = 0; 
descending = 1; 





Example 12—3 Cont'd. on next page 
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Example 12—3 (Cont.) Using SOR Routines to Merge Three Input 
Files in a VAX Pascal Program 


type 
key_buffer_block= 
packed record 


key_type: $uword; 
key_order: $uword ; 
key_offset: $uword ; 
key_length: $uword ; 
end ; 


key_buffer_type= 
packed record 


key_count: $uword ; 
blocks: packed array[1..num_of_keys] of key_buffer_block; 
end; 

record_buffer = packed array[1..1rl] of char; 


record_buffer_descr = 
packed record 
length: $uword; 
dummy: $uword; 
addr: “record_buffer; 
end; 


var 
in_filel, 
in_file2, 
in_file3, 
out_file: text; 
key_buffer: key_buffer_type; 
rec_buffer: record_buffer; 
rec_length: $uword; 


status: integer; 
i: integer ; 
function sor$begin_merge( 

var buffer: key_buffer_type; 
lrl: $uword ; 
mrg_options: integer; 
merge_order: $ubyte; 
Zimmed cmp_rtn: integer := 0; 
immed eql_rtn: integer := 0; 


%immed [unbound] function 
read_record( 
var rec: record_buffer_descr; 
var filenumber: integer; 
var recordsize: $uword): integer 
): integer; extern; 


function sor$return_rec( 
wstdescr rec: record_buffer; 
var rec_size: $uword 
): integer; extern; 


Example 12—3 Cont'd. on next page 
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Example 12—3 (Cont.) Using SOR Routines to Merge Three Input 
Files in a VAX Pascal Program 





function sor$end_sort: integer; extern; 
procedure sys$exit( %immed status : integer ); extern; 


function read_record( 
var rec: record_buffer_descr; 
var filenumber: integer; 
var recordsize: $uword 


): integer; 
procedure readone( var filename: text ); 
begin 
recordsize := QO; 
if eof (filename) 
then 
read_record := ss$_endoffile 
else 
begin 
while not eoln(filename) and (recordsize < rec.length) do 
begin 
recordsize := recordsize + 1; 
read(filename,rec.addr* [recordsize]); 
end; 
readln(filename) ; 
end; 
end; 
begin 
read_record := ss$_normal;: 


case filenumber of 
1: readone(in_filei) ; 
2: readone(in_filed2) ; 
3: readone(in_file3) ; 
otherwise 
read_record := ss$_endoffile; 
end; 
end; 


procedure initfiles; 

begin 

open( in_filei, 'infilel.dat', old ); 
open( in_file2, 'infile2.dat', old ); 
open( in_file3, '‘infile3.dat', old ); 
open( out_file, 'temp.tmp' ); 

reset( in_filei ); 

reset( in_file2 ); 

reset( in_file3 ); 

rewrite( out_file ); 

end; 


procedure error( status : integer ); 


begin 

writeln( 'merge unsuccessful. status=%x', status:8 hex ); 
sys$exit (status) ; 

end; 





Example 12—3 Cont'd. on next page 
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begin 


with key_buffer do 
begin 
key_count := 1; 
with blocks[1] do 


begin 
key_type := dsc$k_dtype_t; 
key_order := ascending; 
key_offset := 0; 
key_length := 5; 
end; 
end; 
initfiles; 


status := sor$begin_merge( key_buffer, l1rl, 
sor$m_seq_check + sor$m_signal, 
merge_order, 0, 0, read_record ); 


repeat 
begin 
rec_length := 0; 
status := sor$return_rec( rec_buffer, rec_length ); 
if odd(status) 
then 
begin 
for i := 1 to rec_length do write(out_file, rec_buffer[i]); 
writeln(out_file) ; 
end; 
end 


until not odd(status) ; 
if status <> ss$_endoffile then error(status) ; 


status := sor$end_sort; 
if not odd(status) then error(status) ; 


writeln( 'merge successful.' ); 


end. 
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Example 12-4 is a VAX Pascal program demonstrating a sort operation using 
a record interface. 


Example 12—4 Using SOR Routines to Sort Records from Two Input Files in a VAX Pascal 
Program 





PASCAL Program 
PROGRAM FILETORECORDSORT (OUTPUT ,SORTOUT) ; 


(* This program calls SOR routines to read and sort records from 
two input files, (PASINPUT1.DAT and PASINPUT2.DAT) and to return 
sorted records to this program to be written to the output file, 
(TEMP.TMP). *) 


(* Declarations for external status codes, and data structures, such as 
the types $UBYTE (an unsigned byte) and $UWORD (an unsigned word). *) 


CONST 

SS$_NORMAL = 1; 
SS$_ENDOFFILE = %X870; 
SOR$GK_RECORD = 1; 
SOR$M_STABLE = 1; 
SOR$M_SEQ_CHECK = 4; 
SOR$M_SIGNAL = 8; 
DSC$K_DTYPE_T = 14; 


TYPE 
$UBYTE = [BYTE] 0. .255; 
$UWORD = [WORD] 0. .65535; 
CONST 
Numberofkeys = 1 ; (* Number of keys for this sort *) 
LRL = 131 ; (* Longest Record Length for output records *) 


(* Key orders *) 


Ascending = 0 ; 
Descending = 1 ; 


TYPE 
Keybufferblock= packed record 
Keytype : $UWORD ; 
Keyorder : $UWORD ; 
Keyoffset : $UWORD ; 
Keylength : $UWORD 
end ; 


(* The keybuffer. Note that the field buffer is a one-component array in 
this program. This type definition would allow a multikeyed sort. *) 


Keybuffer= packed record 
Numkeys : $UWORD ; 
Blocks : packed array[1..Numberofkeys] OF Keybufferblock 
end ; 


(* The record buffer. This buffer will be used to hold the returned 
records from SORT. *) 


Recordbuffer = packed array[1..LRL] of char ; 


(* Name type for input and output files. A necessary fudge for %stdescr 
mechanism. *) 


nametype= packed array[1..13] of char ; 





Example 12—4 Cont'd. on next page 
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Example 12—4 (Cont.) Using SOR Routines to Sort Records from Two Input Files in a VAX 


Pascal Program 


VAR 
Sortout : text ; (* the output file *) 
Buffer : Keybuffer ; (* the actual keybuffer *) 
Sortoptions : integer ; (* flag for sorting options *) 
Sorttype : $UBYTE ; (* sorting process *) 
Numworkfiles : $UBYTE ; (* number of work files *) 
Status : integer ; (* function return status code *) 
Rec : Recordbuffer ; (* a record buffer *) 
Recordlength : $UWORD ; (* the returned record length *) 
Inputname: nametype.; (* input file name *) 
i: integer ; (* loop control variable *) 

(* function and procedure declarations *) 

(* Declarations of SORT functions *) 

(x Note that the following SORT routine declarations 


(+ 


do not use all of the possible routine parameters. *) 
The parameters used MUST have all preceding parameters specified, 
however. *) 


FUNCTION SOR$PASS_FILES 


(,ASTDESCR Inname : nametype ) 
: INTEGER ; EXTERN ; 


FUNCTION SOR$BEGIN_SORT( 


VAR Buffer : Keybuffer ; 

Lrlen : $UWORD ; 

VAR Sortoptions : INTEGER ; 
%IMMED Filesize : INTEGER ; 
%IMMED Usercompare : INTEGER ; 
%IMMED Userequal : INTEGER ; 
VAR Sorttype : $UBYTE ; 

VAR Numworkfiles : $UBYTE ) 

: INTEGER ; EXTERN ; 


FUNCTION SOR$SORT_MERGE 


: INTEGER ; EXTERN ; 


FUNCTION SOR$RETURN_REC( 


%STDESCR Rec : Recordbuffer ; 
VAR Recordsize : $UWORD ) 
: INTEGER ; EXTERN ; 


FUNCTION SOR$END_SORT 


(* 


: INTEGER ; EXTERN ; 


End of the SORT function declarations *) 





Example 12—4 Cont'd. on next page 
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Example 12—4 (Cont.) Using SOR Routines to Sort Records from Two Input Files in a VAX 
Pascal Program 


(* The CHECKSTATUS routine checks the return status for errors. *) 
(* If there is an error, write an error message and exit via sys$exit *) 
PROCEDURE CHECKSTATUS( var status : integer ) ; 


procedure sys$exit( status : integer ) ; extern ; 


begin | (* begin checkstatus *) 
if odd(status) then 
begin 
writeln( ' SORT unsuccessful. Error status = ', status:8 hex ) ; 
SYS$EXIT( status ) ; 
end ; 
end ; (* end checkstatus *) 


(* end function and routine declarations *) 


BEGIN (* begin the main routine *) 


(* Initialize data for one 8-byte character key, starting at record 
offset 0, 3 work files, and the record sorting process *) 


Inputname := 'PASINPUT1.DAT' ; 
WITH Buffer DO 
BEGIN 
Numkeys := 1; 
WITH Blocks[1] DO 
BEGIN 
Keytype := DSC$K_DTYPE_T ; (* Use VMS descriptor data types to 
define SORT data types. *) 
Keyorder := Ascending ; 
Keyoffset :=0 ; 
Keylength := 8 ; 
END ; 
END; 
Sorttype := SOR$GK_RECORD ; (* Use the global SORT constant to 
define the sort process. *) 
Sortoptions := SOR$M_STABLE ; (* Use the global SORT constant to 
define the stable sort option. *) 
Numworkfiles := 3 ; 


(* call the sort routines as a series of functions *) 


(* pass the first filename to SORT *) 
Status := SOR$PASS_FILES( Inputname ) ; 


(* Check status for error. *) 
CHECKSTATUS( Status ) ; 


(* pass the second filename to SORT *) 
Inputname := 'PASINPUT2.DAT' 


Status := SOR$PASS_FILES( Inputname ) ; 


(* Check status for error. *) 
CHECKSTATUS( Status ) ; 


(* initialize work areas and keys *) 
Status := SOR$BEGIN_SORT( Buffer, 0, Sortoptions, 0, 0, 0, 
Sorttype, Numworkfiles ) ; 


Example 12—4 Cont'd. on next page 
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Example 12—4 (Cont.) Using SOR Routines to Sort Records from Two Input Files in a VAX 
Pascal Program 





(* Check status for error. *) 
CHECKSTATUS( Status ) ; 


(* sort the records *) 
Status := SOR$SORT_MERGE ; 


(* Check status for error. *) 
CHECKSTATUS( Status ) ; 


(* Ready output file for writing returned records from SORT. *) 
OPEN( SORTOUT, 'TEMP.TMP' ) ; 
REWRITE( SORTOUT ) ; 


(* Now get the sorted records from SORT. *) 
Recordlength := 0 ; 
REPEAT 

Status := SOR$RETURN_REC( Rec, Recordlength ) ; 


if odd( Status ) 


then (* if successful, write record to output file. *) 
begin 
for i := 1 to Recordlength do 
write( sortout, Rec[i] ) ; (* write each character *) 
writeln (sortout) ; (* end output line *) 
end; 


UNTIL not odd( Status ) ; 


(* If there was just no more data to be returned (eof) continue, otherwise 
exit with an error. *) 
if Status <> SS$_ENDOFFILE then 
CHECKSTATUS( Status ) ; 


(* The sort has been successful to this point. *) 


(* Close the output file *) 
CLOSE( sortout ) ; 


(* clean up work areas and files *) 
Status := SOR$END_SORT ; 


(* Check status for error. *) 
CHECKSTATUS( Status ); 


WRITELN ('SORT SUCCESSFUL') ; 
END. 








SOR Routines 


The following pages describe the individual SOR routines. 
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SOR$BEGIN_MERGE Initialize a Merge Operation 


The SOR$BEGIN_MERGE routine initializes the merge operation by opening 
the input and output files and by providing the number of input files, the 
key specifications, and the merge options. 





FORMAT SORS$SBEGIN_MERGE [key-buffer] [,/rl] [, options] 
[,merge_order] [,user_compare] 
[,user_equall] [,user_input] 





[,context] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS key_buffer 


VMS usage: vector_word_unsigned. 
type: word (unsigned) 
access: read only 

mechanism: by reference 


Array of words describing the keys on which you plan to merge. The 
key_buffer argument is the address of an array containing the key 
descriptions. 


The first word of this array contains the number of keys described (up to 
255). Following the first word, each key is described (in order of priority) 
in blocks of four words. The four words specify the key’s data type, order, 
offset, and length, respectively. 


The first word of the block specifies the key’s data type. The following data 
types are accepted: 

DSC$K_DTYPE_Z Unspecified (uninfluenced by collating sequence) 
DSC$K_DTYPE_B Byte integer (signed) 

DSC$K_DTYPE_BU Byte (unsigned) 

DSC$K_DTYPE_W Word integer (signed) 

DSC$K_DTYPE_WU Word (unsigned) 

DSC$K_DTYPE_L Longword integer (signed) 

DSC$K_DTYPE_LU Longword (unsigned) 

DSC$K_DTYPE_O Quadword integer (signed) 
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DSC$K_DTYPE_QU 
DSC$K_DTYPE_O 
DSC$K_DTYPE_OU 
DSC$K_DTYPE_F 
DSC$K_DTYPE_D 
DSC$K_DTYPE_G 
DSC$K_DTYPE_H 
DSC$K_DTYPE_T 
DSC$K_DTYPE_NU 
DSC$K_DTYPE_NL 
DSC$K_DTYPE_NLO 
DSC$K_DTYPE_NR 
DSC$K_DTYPE_NRO 
DSC$K_DTYPE_NZ 
DSC$K_DTYPE_P 


Quadword (unsigned) 
Octaword integer (signed) 


~ Octaword (unsigned) 


Single-precision floating 
Double-precision floating 

G-format floating 

H-format floating 

Text (may be influenced by collating sequence) 
Numeric string, unsigned 

Numeric string, left separate sign 
Numeric string, left overpunched sign 
Numeric string, right separate sign 
Numeric string, right overpunched sign 
Numeric string, zoned sign 

Packed decimal string 


The VAX Procedure Calling and Condition Handling Standard, documented 
in Chapter 2 in the Introduction to VMS System Routines, describes each of 


these data types. 


The second word of the block specifies the key order: 0 for ascending order, 1 
for descending order. The third word of the block specifies the relative offset 
of the key in the record. (Note that the first byte in the record is at position 
0.) The fourth word of the block specifies the key length in bytes (in digits 
for packed decimal—DSC$K_DTYPE_P). 


If you do not specify the key_buffer argument, you must pass either a key 
comparison routine or use a specification file to define the key. 


Irl 
_ VMS usage: 


type: 
access: 
mechanism: 


word_unsigned 
word (unsigned) 
read only 

by reference 


Length of the longest record that will be released for merging. The Irl 
argument is the address of a word containing the length. If the input file 

is on a disk, this argument is not required. It is required when you use the 
record interface. For VFC records, this length must include the length of the 
fixed-length portion of the record. 


options 


VMS usage: mask—longword 


type: 
access: 


longword (unsigned) 
read only 


mechanism: by reference 


Flags that identify merge options. The options argument is the address of a 
-longword bit mask whose settings determine the merge options selected. The 
following table lists and describes the bit mask values available. 


SOR-18 


Sort/Merge (SOR) Routines 
SORSBEGIN_MERGE 


Flag Description 

SOR$M_STABLE Keeps records with equal keys in the same order as they 
appeared on input. 

SOR$M_EBCDIC Orders ASCII character keys according to EBCDIC 
collating sequence. No translation takes place. 

SOR$M_MULTI Orders character keys according to the multinational 


collating sequence, which collates the international 
character set. 


SOR$M_NOSIGNAL Returns a status code instead of signaling errors. (This 
is the default behavior.) 


SOR$M_NODUPS Omits records with duplicate keys. You cannot use this 
option if you specify your own equal-key routine. 


SOR$M_SEQ_CHECK Requests an “out of order” error return if an input file 
is not already in sequence. By default, this check is 
not done. You must request sequence checking if you 
specify an equal-key routine. 


All other bits in the longword are reserved and must be zero. 


merge_order | 

VMS usage: byte_unsigned 
type: byte (unsigned) 
access: read only 
mechanism: by reference 


Number of input streams to be merged. The merge_order argument is the 
address of a byte containing the number of files (1 through 10) to be merged. 
When you use the record interface on input, this argument is required. 


user_compare 


VMS usage: procedure 

type: procedure entry mask 
access: function call 
mechanism: by reference 


Routine that compares records to determine their merge order. The user_ 
compare argument is the address of the entry mask for this user-written 
routine. If you do not specify the key_buffer argument or if you define key 
information in a specification file, this argument is required. 


MERGE calls the comparison routine with five reference arguments—ADRS1, 
ADRS2, LENG1, LENG2, CNTX—corresponding to the addresses of the two 
records to be compared, the lengths of these two records, and the context 
longword. 


The comparison routine must return a 32-bit integer value: 
e -1 if the first record collates before the second 
e 0 if the records collate as equal 


e 61 if the first record collates after the second 
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user_equal 

VMS usage: procedure 

type: procedure entry mask 
access: function call 


mechanism: by reference 


Routine that resolves the merge order when records have duplicate keys. 
The user_equal argument is the address of the entry mask for this user- 
written routine. If you specify SOR65M—STABLE or SORSM—NODUPS in the 
options argument, do not use this argument. 


MERGE calls the duplicate key routine with five reference arguments— 
ADRS1, ADRS2, LENG1, LENG2, CNTX—corresponding to the addresses 
of the two records that compare equally, the lengths of the two records that 
compare equally, and the context longword. 


The routine must return one of the following 32-bit condition codes. 


Code Description 


SOR$_DELETE1 Delete the first record from the merge. 
SOR$_DELETE2 Delete the second record from the merge. 
SOR$_DELBOTH Delete both records from the merge. 
SS$_NORMAL Keep both records in the merge. 


Any other failure value causes the error to be signaled or returned. Any other 
success value causes an undefined result. 


user_input 


VMS usage: procedure 

type: procedure entry mask 
access: function call 
mechanism: by reference 


Routine that releases records to the merge operation. The user_input 
argument is the address of the entry mask for this user-written routine. 
SOR$BEGIN—MERGE and SOR$RETURN-_REC call this routine until all 
records have been passed. 


This input routine must read (or construct) a record, place it in a record buffer, 
store its length in an output argument, and then return control to MERGE. 


The input routine must accept the following four arguments: 
e A descriptor of the buffer where the routine must place the record 


° A longword, passed by reference, containing the stream number from 
which to input a record (the first file is 1, the second 2, and so on) 


e A word, passed by reference, where the routine must return the actual 
length of the record 


e The context longword, passed by reference 


The input routine must also return one of the following status values: 


¢ SS$_NORMAL or any other success status causes the merge operation to 
continue. 
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e SS$_ENDOFFILE indicates that no more records are in the file. The 
contents of the buffer are ignored. 


e Any other error status terminates the merge operation and passes 
the status value back to the caller of SOR$BEGIN—MERGE or 
SOR$RETURN_REC. 


context 

VMS usage: context 

type: longword (unsigned) 
access: modify 


mechanism: by reference 


Value that distinguishes between multiple, concurrent SORT /MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT/MERGE 
routine for a particular sort or merge operation, the context longword must 
equal zero. SORT/MERGE then stores a value in the longword to identify 
the operation just initiated. When you make subsequent routine calls for 

the same operation, you must pass the context value that was supplied by 
SORT /MERGE. 





DESCRIPTION 


The SOR$BEGIN_MERGE routine initializes the merge process by passing 
arguments that provide the number of input streams, the key specifications, 
and any merge options. 


You must define the key by passing either the key buffer address argument 
or your own comparison routine address. (You can also define the key in a 
specification file and call the SOR$SPEC_FILE routine.) 


The SOR$BEGIN_MERGE routine initializes the merge process in the file, 
record, and mixed interfaces. For record interface on input, you must also 
pass the merge order, the input routine address, and the longest record 
length. For files not on disk, you must pass the longest record length. 


Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, you should use 
LIBS|MATCH_COND if you want to check for a specific status. 





CONDITION 
VALUES 
RETURNED 


SS$_NORMAL Success. 

SOR$_BADDTYPE Invalid or unsupported CDD datatype. 
SOR$_BADLENOFF Length and offset must be multiples of 8 bits. 
SOR$_BADLOGIC Internal logic error detected. 
SOR$_BADOCCURS Invalid OCCURS clause. 

SOR$_BADOVRLAY Invalid overlay structure. 

SOR$_BADPROTCL Node is an invalid CDD object. 
SOR$_BAD_KEY Invalid key specification. 

SOR$_BAD_LRL Record length n greater than specified longest 


record length. 
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SOR$_BAD_MERGE 
SOR$_BAD_ORDER 
SOR$_BAD_SRL 
SOR$_BAD_TYPE 
SOR$_CDDERROR 
SOR$_CLOSEIN 
SOR$_CLOSEOUT 
SOR$_COL_CHAR 
SOR$_COL_CMPLX 
SOR$_COL_PAD 
SOR$_COL _THREE 
SOR$_ENDDIAGS 
SOR$_ILLBASE 
SOR$_ILLLITERL 
SOR$_ILLSCALE 
SOR$_INCDIGITS 


SOR$_INCNODATA 
SOR$_INCNOKEY 
SOR$_IND_OVR 
SOR$_KEY AMBINC 
SOR$_KEYED 


SOR$_KEY_LEN 
SOR$_LRL_MISS 
SOR$_MISLENOFF 
SOR$_MISS_PARAM 
SOR$_MULTIDIM 
SOR$_NODUPEXC 


SOR$_NOTRECORD 
SOR$_NUM_KEY 
SOR$_OPENIN 
SOR$_OPENOUT 
SOR$_READERR 
SOR$_RTNERROR 
SOR$_SIGNCOMPQ 


SOR$_SORT_ON 
SOR$_SPCIVC 
SOR$_SPCIVD 
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Number of work files must be between O and 10. 
Merge input is out of order. 

Record length n is too short to contain keys. 
Invalid sort process specified. 

CDD error at node ‘name’. 

Error closing ‘file’ as input. 

Error closing ‘file’ as output. 

Invalid character definition. 

Collating sequence is too complex. 

Invalid pad character. 

Cannot define 3-byte collating values. 

Completed with diagnostics. 

Nondecimal base is invalid. 

Record containing symbolic literals is unsupported. 
Nonzero scale invalid for floating-point data item. 


Number of digits is not consistent with the type or 
length of item. 


Include specification references no data, at line n. 
Include specification references no keys, at line n. 
Indexed output file must already exist. 

Key specification is ambiguous or inconsistent. 


Mismatch between SORT/MERGE keys and primary 
file key. 


Invalid key length, key number n, length n. 
Longest record length must be specified. 
Length and offset required. 

A required subroutine argument is missing. 
Invalid multidimensional OCCURS. 


Equal-key routine and no-duplicates option cannot 
both be specified. 


Node ‘name’ is a name, not a record definition. 
Too many keys specified. 

Error opening ‘file’ as input. 

Error opening ‘file’ as output. 

Error reading ‘file’. 

Unexpected error status from user-written routine. 


Absolute Date and Time data type represented in 
one-second units. 


Sort or merge routines called in incorrect order. 
Invalid collating sequence specification at line n. 
Invalid data type at line n. 


SOR$_SPCIVF 
SOR$_SPCIVI 
SOR$_SPCIVK 
SOR$_SPCIVP 
SOR$_SPCIVS 
SOR$_SPCIVX 
SOR$—SPCMIS 
SOR$_SPCOVR 
SOR$_SPCSIS 
SOR$_SRTIWA 


SOR$_STABLEEX 


SOR$_SYSERROR 

SOR$_UNDOPTION 

SOR$_UNSUPLEVL 
SOR$_WRITEERR 
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Invalid field specification at line n. 

Invalid include or omit specification at line n. 
Invalid key or data specification at line n. 
Invalid sort process at line n. 

Invalid specification at line n. 

Invalid condition specification at line n. 
Invalid merge specification at line n. 
Overridden specification at line n. 

Invalid sort specification at line n. 


Insufficient space. The specification file is too 
complex. 


Equal-key routine and stable option cannot both be 
specified. 


System service error. 

Undefined option flag was set. 
Unsupported core level for record ‘name’. 
Error writing ‘file’. 
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SORSBEGIN_SORT Begin a Sort Operation 











The SOR$BEGIN_SORT routine initializes a sort operation by opening input 
and output files and by passing the key information and any sort options. 


FORMAT SORS$BEGIN_SORT  [key_buffer] [,Irl] [,options] 
[,file_alloc] [,user_compare] 
[,user_equal] [,sort_process] 
[,work_files] [, context] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS _ key_buffer 
VMS usage: vector_word_unsigned 
type: word (unsigned) 
access: read only 


SOR-24 


mechanism: by reference 


Array of words describing the keys on which you plan to sort. The key— 
buffer argument is the address of an array containing the key descriptions. 


The first word of this array contains the number of keys described (up to 
255). Following the first word, each key is described (in order of priority) 
in blocks of four words. The four words specify the key’s data type, order, 
offset, and length, respectively. 


The first word of the block specifies the data type of the key. The following 
data types are accepted: 

DSC$K_DTYPE_Z Unspecified (uninfluenced by collating sequence) 
DSC$K_DTYPE_B Byte integer (signed) 

DSC$K_DTYPE_BU _ Byte (unsigned) 

DSC$K_DTYPE_W Word integer (signed) 

DSC$K_DTYPE_WU Word (unsigned) 

DSC$K_DTYPE_L Longword integer (signed) 

DSC$K_DTYPE_LU Longword (unsigned) 

DSC$K_DTYPE_O Quadword integer (signed) 

DSC$K_DTYPE_OU Quadword (unsigned) 

DSC$K_DTYPE_O Octaword integer (signed) 
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DSC$K_DTYPE_OU Octaword (unsigned) 


DSC$K_DTYPE_F Single-precision floating 

DSC$K_DTYPE_D Double-precision floating 

DSC$K_DTYPE_G G-format floating 

DSC$K_DTYPE_H H-format floating 

DSC$K_DTYPE_T Text (may be influenced by collating sequence) 


DSC$K_DTYPE_NU Numeric string, unsigned 
DSC$K_DTYPE_NL Numeric string, left separate sign 
DSC$K_DTYPE_NLO Numeric string, left overpunched sign 
DSC$K_DTYPE_NR Numeric string, right separate sign 
DSC$K_DTYPE_NRO Numeric string, right overpunched sign 
DSC$K_DTYPE_NZ Numeric string, zoned sign 
DSC$K_DTYPE_P Packed decimal string 


The VAX Procedure Calling and Condition Handling Standard, documented 
in Chapter 2 in the Introduction to VMS System Routines, describes each of 
these data types. 


The second word of the block specifies the key order: 0 for ascending order, 1 
for descending order. The third word of the block specifies the relative offset 
of the key in the record. Note that the first byte in the record is at position 
0. The fourth word of the block specifies the key length in bytes (in digits for 
packed decimal—DSC$K_DTYPE_P). 


The key_buffer argument specifies the address of the key buffer in the 
data area. If you do not specify this argument, you must either pass a key 
comparison routine or use a specification file to define the key. 


Irl 

VMS usage: word_unsigned 
type: word (unsigned) 
access: read only 


mechanism: by reference 


Length of the longest record that will be released for sorting. The Irl 
argument is the address of a word containing the length. This argument 

is not required if the input file(s) is on disk but is required when you use the 
record interface. For VFC records, this length must include the length of the 
fixed-length portion of the record. 


options 

VMS usage: mask—_longword 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Flags that identify sort options. The options argument is the address of a 
longword bit mask whose settings determine the merge options selected. The 
following table lists and describes the bit mask values available. 
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Flags Description 
SOR$M_STABLE Keeps records with equal keys in the same order in which 


they appeared on input. With multiple input files that have 
records that collate as equal, records from the first input 
file are placed before the records from the second input 
file, and so on. 


SOR$M_EBCDIC Orders ASCII character keys according to EBCDIC collating 
sequence. No translation takes place. 
SOR$M_MULTI Orders character keys according to the multinational 


collating sequence, which collates the international 
character set. 


SOR$M_NOSIGNAL _ Returns the condition code instead of signaling an error. 
The default is SOR5M_NOSIGNAL. 


SOR$M_NODUPS Omits records with duplicate keys. You cannot use this 
option if you specify your own equal-key routine. 


All other bits in the longword are reserved and must be zero. 


file_alloc 


VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Input file size in blocks. The file_alloc argument is the address of a longword 
containing the size. This argument is never required because, by default, 
SORT uses the allocation of the input files. If you are using the record 
interface or if the input files are not on disk, the default is 1000 blocks. 


However, you can use this optional argument to improve the efficiency of the 
sort by adjusting the amount of resources the sort process allocates. 


user_compare 
VMS usage: procedure 

type: procedure entry mask 
access: function call 
mechanism: by reference 


User-written routine that compares records to determine their sort order. The 
user_compare argument is the address of the entry mask for this user-written 
routine. If you do not specify the key_buffer argument or if you define key 
information in a specification file, this argument is required. 


SORT/MERGE calls the comparison routine with five reference arguments— 
ADRS1, ADRS2, LENG1, LENG2, CNTX—corresponding to the addresses of 
the two records to be compared, the lengths of these two records, and the 
context longword. 


The comparison routine must return a 32-bit integer value: 
e -1 if the first record collates before the second 
¢ 0 if the records collate as equal 


e 1 if the first record collates after the second 
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user_equal 

VMS usage: procedure 

type: procedure entry mask 
access: function call 


mechanism: by reference 


User-written routine that resolves the sort order when records have duplicate 
keys. The user_equal argument is the address of the entry mask for this 
user-written routine. If you specify SOR6M—STABLE or SOR$SM—NODUPS 
in the options argument, do not use this argument. 


SORT/MERGE calls the duplicate key routine with five reference 
arguments—ADRS1, ADRS2, LENG1, LENG2, CNTX—corresponding to 

the addresses of the two records that compare equally, the lengths of the two 
records that compare equally, and the context longword. 


The routine must return one of the following 32-bit integer condition codes. 


Code Description 


SOR$_DELETE 1 Delete the first record from the sort. 
SOR$_DELETE2 Delete the second record from the sort. 
SOR$_.DELBOTH Delete both records from the sort. 

’ SS$ NORMAL Keep both records in the sort. 


Any other failure value causes the error to be signaled or returned. Any other 
success value causes an undefined result. 


sort_process 

VMS usage: byte_unsigned 
type: byte (unsigned) 
access: read only 


mechanism: by reference 


Code indicating the type of sort process. The sort_process argument is the 
address of a byte whose value indicates whether the sort type is record, tag, 
index, or address. The default is record. If you select the record interface on 
input, you can use only a record sort process. 


To specify a byte containing the value for the type of sort process you want, 
enter one of the following: 


e SOR$GK_RECORD (record sort) 

¢ SOR$GK_TAG (tag sort) 

¢ SOR$GK—ADDRESS (address sort) 
e SOR$GK_INDEX (index sort) 
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work_files 

VMS usage: byte_unsigned 
type: byte (unsigned) 
access: read only 


mechanism: by reference 


Number of work files to be used in the sorting process. The work_files 
argument is the address of a byte containing the number of work files; 
permissible values range from 0 through 10. 


By default, SORT creates two temporary work files when it needs them and 
determines their size from the size of your input files. By increasing the 
number.of work files, you can reduce their individual size so that each fits 
into less disk space. You can also assign each of them to different disk- 
structured devices. 


context 

VMS usage: context 

type: longword (unsigned) 
access: write only 


mechanism: by reference 


Value that distinguishes between multiple, concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT/MERGE 
routine for a particular sort or merge operation, the context longword must 
equal zero. SORT/MERGE then stores a value in the longword to identify 
the operation just initiated. When you make subsequent routine calls for the 
same operation, you must pass the context value supplied by SORT/MERGE. 





DESCRIPTION 
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The SOR$BEGIN_SORT routine initializes the sort process by setting up sort 
work areas and provides key specification and sort options. 


Specify the key information with the key_buffer argument, with the 
user_compare argument, or in a specification file. If no key information 
is specified, the default (character for the entire record) is used. 


You must use the SOR$BEGIN—SORT routine to initialize the sort process for 
the file, record, and mixed interfaces. For record interface on input, you must 
use the Irl (longest record length) argument. 


Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, if you want to 
check for a specific status, you should use LIBS|MATCH_COND. 


Sort/Merge (SOR) Routines 


SORSBEGIN_SORT 





CONDITION 
VALUES 
RETURNED 


SS$_NORMAL 
SOR$_BADLOGIC 
SOR$_BAD_KEY 
SOR$_BAD_LRL 


SOR$_BAD_MERGE 
SOR$_BAD_TYPE 
SOR$_ENDDIAGS 
SOR$_INSVIRMEM 
SOR$_KEY AMBINC 
SOR$S_KEY_LEN 
SOR$_LRL_MISS 
SOR$_NODUPEXC 


SOR$_NUM_KEY 
SOR$_RTNERROR 
SOR$_SORT_ON 
SOR$_STABLEEXC 


SOR$S_SYSERROR 
SOR$_UNDOPTION 


Success. 
Internal logic error detected. 
Invalid key specification. 


Record length n greater than specified longest 
record length. 


Number of work files must be between O and 10. 
Invalid sort process specified. 

Completed with diagnostics. 

Insufficient virtual memory. 

Key specification is ambiguous or inconsistent. 
Invalid key length, key number n, length n. 
Longest record length must be specified. 


Equal-key routine and no-duplicates option cannot 
both be specified. 


Too many keys specified. 
Unexpected error status from user-written routine. 
Sort or merge routine called in incorrect order. 


Equal-key routine and stable option cannot both be 
specified. 


System service error. 
Undefined option flag was set. 
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SORSDTYPE Define Data Type 


The SORSDTYPE routine defines a key data type that is not normally 
supported by SORT/MERGE. This routine returns a key data type code 
that can be used in the key_buffer argument to SOR$BEGIN_SORT or 
SOR$BEGIN_MERGE to describe special key data types (such as extended 
data types and NCS collating sequences). 





FORMAT 


SORSDTYPE [context], dtype—_code, usage, p1 





RETURNS 


VMS usage: Cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 
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context 

VMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Value that distinguishes between multiple, concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT/MERGE 
routine for a particular sort or merge operation, the context longword must 
equal zero. SORT/MERGE then stores a value in the longword to identify 
the operation just initiated. When you make subsequent routine calls for the 
same operation, you must pass the context value supplied by SORT /MERGE. 


dtype_code 

VMS usage: word_unsigned 
type: word (unsigned) 
access: write only 
mechanism: by reference 


Returned key data type code. The dtype—code argument is the address of a 
word into which SORT/MERGE writes the key data type code that can be 
used in the key_buffer argument to SOR$BEGIN_SORT or SOR$BEGIN— 
MERGE. 
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usage 
VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Address of a longword containing a code that indicates the interpretation 
of the p1 argument. The following table lists and describes the valid usage 
codes. 


Flag Description 


SOR$K ROUTINE The p1 argument should be interpreted as the 
address of the entry mask of a routine that SORT 
/MERGE will call to compare keys described by the 
dtype_code returned by the call to SOR$DTYPE. 

SOR$SK_NCS_TABLE The p1 argument should be interpreted as the 
address of a collating sequence identification returned 
-by a call to NCS$GET_CS. SORT/MERGE will use this 
collating sequence to compare keys described by the 
dtype_code returned by the call to SOR$DTYPE. 


If SOR$K_ROUTINE is returned, SORT/MERGE will call this routine with 
five reference arguments—ADRS1, ADRS2, LENG1, LENG2, CNTX— 
corresponding to the addresses of the two keys to be compared, the lengths 
of the two keys, and the context longword. 


The comparison routine must return a 32-bit integer value: 
e -1 if the first key collates before the second 

e (ifthe keys collate as equal 

e +1 if the first key collates after the second 


pt 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Address of an entry mask of a routine or the address of a collating sequence 
identification, depending on the usage argument. 





DESCRIPTION 


Call SOR$DTYPE to define a key data type not normally supported by 
SORT /MERGE. 


If your SORT/MERGE application needs to compare dates (for example) that 
are stored in text form and that is the only key in the records, then use the 
user_compare argument to SOR$BEGIN—SORT or SOR$BEGIN_MERGE. 
However, if the records contain several keys besides the dates in text form, 
it may be easier to call SORS$DTYPE to allocate a key data type code that 
can then be used in the the key_buffer argument to SOR$6BEGIN—SORT or 
SOR$BEGIN—MERGE. | 
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SOR$DTYPE 
If your SORT/MERGE application has a string key that should be collated 
by a collating sequence defined by the VMS National Character Set (NCS) 
Utility, the NCS$GET_CS routine can be used to fetch the collating sequence 
definition, and SOR$DTYPE can be called to allocate a key data type code for 
the collating sequence. This key data type code can then be used to describe 
keys that should be compared by this collating sequence. 

CONEiON SS$_NORMAL S 

b oolatat SORS SORT_ON ae i lled in i d 

RETURNED a = ort or merge routine called in incorrect order. 
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SORSEND_SORT End a Sort Operation 


The SOR$END_SORT routine does cleanup functions, such as closing files 
and releasing memory. 














FORMAT SORSEND_SORT [context] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 
ARGUMENT context 
VMS usage: context 
type: longword 
access: write only 
mechanism: by reference 
Value that distinguishes between multiple, concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT/MERGE 
routine for a particular sort or merge operation, the context longword must 
equal zero. SORT/MERGE then stores a value in the longword to identify 
the operation just initiated. When you make subsequent routine calls for the 
same operation, you must pass the context value supplied by SORT /MERGE. 
DESCRIPTION The SOR$END_SORT routine ends a sort or merge operation, either at the 


end of a successful process or between calls because of an error. If an error 
status is returned, you must call SOR$END_SORT to release all allocated 
resources. In addition, this routine may be called at any time to close files 
and release memory. 


The value of the optional context argument is cleared when the 
SOR$END_SORT routine completes its operation. 


Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, if you want to 
check for a specific status, you should use LIB5MATCH_COND. 
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CONDITION 

VALUES SS$_NORMAL Success. | | | 

RETURNED SOR$_CLOSEIN Error closing ‘file’ as input. 
SOR$_CLOSEOUT Error closing ‘file’ as output. 
SOR$_ENDDIAGS Completed with diagnostics. 
SOR$_END__SORT SORT/MERGE terminated, context = ‘context’. 
SOR$_SYSERROR System service error. 
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SORSPASS_FILES Pass File Names 


The SOR$PASS_FILES routine passes the names of input and output files 
and output file characteristics to SORT or MERGE. 











FORMAT SORS$SPASS_FILES [inp_desc] [, out_desc] [,org] [,rfm] 
[,bks] [bls] [,mrs] [,alq] [,fop] [,fsz] 
[,context] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS inp_desc 
VMS usage: char_string 
type: character-coded text string 
access: read only 


mechanism: by descriptor 


Input file specification. The inp_desc argument is the address of a descriptor 
pointing to the file specification. In the file interface, you must call 
SOR$PASS_FILES to pass SORT the input file specifications. For multiple 
input files, call SOR$PASS_FILES once for each input file, passing one input 
file specification descriptor each time. 


In the mixed interface, if you are using the record interface on input, pass 
only the output file specification; do not pass any input file specifications. 
If you are using the record interface on output, pass only the input file 
specifications; do not pass an output file specification or any of the optional 
output file arguments. 


out_desc 

VMS usage: char_string 

type: character-coded text string 
access: read only 


mechanism: by descriptor 


Output file specification. The out—_desc argument is the address of a 
descriptor pointing to the file specification. In the file interface, when you 
call SOR$PASS_FILES, you must pass the output file specification. Specify 
the output file specification and characteristics only once, as part of the first 
call, as in the following: . 


Call SOR$PASS_FILES(Input1, Output) 
Call SOR$PASS_FILES (Input2) 
Call SOR$PASS_FILES(Input3) 
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In the mixed interface, if you are using the record interface on input, pass 
only the output file specification; do not pass any input file specifications. 
If you are using the record interface on output, pass only the input file 
specifications; do not pass an output file specification or any of the optional 
output file arguments. 


org 

VMS usage: byte—_unsigned 
type: byte (unsigned) 
access: read only 


mechanism: by reference 


File organization of the output file, if different from the input file. The org 
argument is the address of a byte whose value specifies the organization of 
the output file; permissible values include the following: 


FAB$C_SEQ 
FAB$C_REL 
FAB$C_IDX 


For the record interface on input, the default value is sequential. For the file 
interface, the default value is the file organization of the first input file for 
record or tag sort and sequential for address and index sort. 


For more information about the FAB fields, see the VMS Record Management 
Services Manual. . 


rfm 

VMS usage: byte_unsigned 
type: byte (unsigned) 
access: read only 


mechanism: by reference 


Record format of the output file, if different from the input file. The rfm 
argument is the address of a byte whose value specifies the record format of 
the output file; permissible values include the following: 


FAB$C_FIX 
FAB$C_VAR 
FAB$C_VFC 


For the record interface on input, the default value is variable. For the file 
interface, the default value is the record format of the first input file for record 
or tag sort and fixed format for address or index sort. For the mixed interface 
with record interface on input, the default value is variable format. 


bks 

VMS usage: byte_unsigned 
type: byte (unsigned) 
access: read only 


mechanism: by reference 


Bucket size of the output file, if different from the first input file. The bks 
argument is the address of a byte containing this size. Use this argument with 
relative and indexed-sequential files only. If the bucket size of the output file 
is to differ from that of the first input file, specify a byte to indicate the bucket 
size. Acceptable values are from 1 to 32. If you do not pass this argument— 
and the output file organization is the same as that of the first input file—the | 
bucket size defaults to the value of the first input file. If the file organizations 
differ or if the record interface is used on input, the default value is 1 block. 
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bls 

VMS usage: word_unsigned 
type: word (unsigned) 
access: read only 


mechanism: by reference 


Block size of a magnetic tape output file. The bls argument is the address 

of a word containing this size. Use this argument with magnetic tapes only. 
Permissible values range from 20 to 65,532. However, to ensure compatibility 
with non-DIGITAL systems, ANSI standards require that the block size be 
less than or equal to 2048. 


The block size defaults to the block size of the input file magnetic tape. If the | 
input file is not on magnetic tape, the output file block size defaults to the 
size used when the magnetic tape was mounted. 


mrs 

VMS usage: word_unsigned 
type: word (unsigned) 
access: read only 


mechanism: by reference 


Maximum record size for the output file. The mrs argument is the address of 
a word specifying this size. Following are acceptable values for each type of 
file. 


File Organization Acceptable Value 
Sequential 0 to 32,767 
Relative 0 to 16,383 
Indexed sequential 0 to 16,362 


If you omit this argument or if you specify a value of 0, SORT does not check 
maximum record size. 


If you do not specify this argument, the default is based on the output file 
organization and format, unless the organization is relative or the format is 
fixed. The longest output record length is based on the longest calculated 
input record length, the type of sort, and the record format. 


alq 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Number of preallocated output file blocks. The alq argument is the address 
of a longword specifying the number of blocks you want to preallocate to the 
output file. Acceptable values range from 1 to 4,294,967,295. 


Pass this argument if you know your output file allocation will be larger or 
smaller than that of your input files. The default value is the total allocation 
of all the input files. If the allocation cannot be obtained for any of the input 
files or if record interface is used on input, the file allocation defaults to 1000 
blocks. 
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fop 

VMS usage: mask—longword 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


File-handling options. The fop argument is the address of a longword whose 
bit settings determine the options selected. For a list of valid options, see the 
description of the FAB$L_FOP field in the VMS Record Management Services 
Manual. By default, only the DFW (deferred write) option is set. If your 
output file is indexed, you should set the CIF (create if) option. 


fsz 

VMS usage: byte_unsigned 
type: byte (unsigned) 
access: read only 


mechanism: by reference 


Size of the fixed portion of VFC records. The fsz argument is the address of a 
byte containing this size. If you do not pass this argument, the default is the 
size of the fixed portion of the first input file. If you specify the VFC size 

as 0, RMS defaults the value to 2 bytes. 


context 

VMS usage: context 

type: longword (unsigned) 
access: write only 


mechanism: by reference 


Value that distinguishes between multiple concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT/MERGE 
routine for a particular sort or merge operation, the context longword must 
equal zero. SORT/MERGE then stores a value in the longword to identify 
the operation just initiated. When you make subsequent routine calls for the 
same operation, you must pass the context value supplied by SORT /MERGE. 





DESCRIPTION 
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The SOR$PASS_FILES routine passes input and output file specifications to 
SORT. The SOR$PASS_FILES routine must be repeated for multiple input 
files. The output file name string and characteristics should be specified only 
in the first call to SOR$PASS_FILES. 


This routine also accepts optional arguments that specify characteristics for 
the output file. By default, the output file characteristics are the same as the 
first input file; specified output file characteristics are used to change these 
defaults. 


Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, if you want to 
check for a specific status, you should use LIB|MATCH_COND. 
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CONDITION 

VALUES SS$_NORMAL SUSeesS: - 

RETURNED SOR$_DUP_OUTPUT Output file has already been specified. 
SOR$_ENDDIAGS Completed with diagnostics. 
SOR$_INP_FILES Too many input files specified. 
SOR$_SORT_ON Sort or merge routine called in incorrect order. 
SOR$_SYSERROR System service error. 
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SORSRELEASE_REC Pass One Record to Sort 


The SOR$RELEASE_REC routine is used with the record interface to pass 
one input record to SORT or MERGE. 





FORMAT 


SORS$RELEASE_REC desc [,context] 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


desc 

VMS usage: char_string 

type: character-coded text string 
access: read only © 

mechanism: by descriptor 


Input record buffer. The desc argument is the address of a descriptor 
pointing to the buffer containing the record to be sorted. If you use the 
record interface, this argument is required. 


context 


VMS usage: context 
type: longword 
access: modify 
mechanism: by reference 


Value that distinguishes between multiple, concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT/MERGE 
routine for a particular sort or merge operation, the context longword must 
equal zero. SORT/MERGE then stores a value in the longword to identify 
the operation just initiated. When you make subsequent routine calls for the 
same operation, you must pass the context value supplied by SORT/MERGE. 





DESCRIPTION 


SOR-—40 


Call SOR$RELEASE_REC to pass records to SORT or MERGE with the 
record interface. SOR$RELEASE_REC must be called once for each record to 
be sorted. 


Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, if you want to 
check for a specific status, you should use LIBS}MATCH—COND. 
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CONDITION 
VALUES 
RETURNED 


_ SS$_NORMAL 


SOR$_BADLOGIC 
SOR$_BAD_LRL 


SOR$_BAD_SRL 
SOR$_ENDDIAGS 
SOR$_EXTEND 
SOR$_MISS_PARAM 
SOR$_NO_WRK 


SOR$_OPENOUT 
SOR$_OPERFAIL 
SOR$_OPREPLY 

SOR$_READERR 
SOR$_REQ _ALT 


SOR$_RTNERROR 
SOR$_SORT_ON 
SOR$_SYSERROR 
SOR$_USE_ALT 
SOR$_WORK_DEV 


Success. 
Internal logic error detected. 


Record length n greater than longest specified 
record length. 


Record length n too short to contain keys. 
Completed with diagnostics. 

Unable to extend work file for needed space. 
The desc argument is missing. 


Work files required, cannot do sort in memory as 
requested. 


Error opening ‘file’ as output. 
Error requesting operator service. 
Operator reply is ‘reply’. 

Error reading ‘file’. 


Specify alternate ‘name’ file (or nothing to try 
again). 


Unexpected error status from user-written routine. 
Sort or merge routines called in incorrect order. 
System service error. 

Using alternate file ‘name’. 


Work file ‘name’ must be on random access local 
device. 
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SOR$SRETURN_REC Return One Sorted Record 


The SOR$RETURN_REC routine is used with the record interface to return 
one sorted or merged record to a program. 











FORMAT SOR$SRETURN_REC desc [,length] [,context] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in.RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS desc 
VMS usage: char_string 
type: character-coded text string 
access: write only 
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mechanism: by descriptor 


Output record buffer. The desc argument is the address of a descriptor 
pointing to the buffer that receives the sorted or merged record. 


length 

VMS usage: word_unsigned 
type: word (unsigned) 
access: write only 


mechanism: by reference 


Length of the output record. The length argument is the address of a word 
receiving the length of the record returned from SORT/MERGE. 


context | 

VMS usage: context 

type: longword (unsigned) 
access: modify 


mechanism: by reference 


Value that distinguishes between multiple, concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT/MERGE 
routine for a particular sort or merge operation, the context longword must 
equal zero. SORT/MERGE then stores a value in the longword to identify 
the operation just initiated. When you make subsequent routine calls for the 
same operation, you must pass the context value supplied by SORT/MERGE. 


Sort/Merge (SOR) Routines 
SOR$RETURN_REC 





DESCRIPTION 


Call the SOR$RETURN_REC routine to release the sorted or merged records 
to a program. Call this routine once for each record to be returned. 


SOR$RETURN_REC places the record into a record buffer that you set up in 
the program’s data area. After SORT has successfully returned all the records 
to the program, it returns the status code SS$_ENDOFFILE, which indicates 
that there are no more records to return. 


Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, if you want to 
check for a specific status, you should use LIB; MATCH—COND. 





CONDITION 
VALUES 
RETURNED 


SS$_NORMAL Success. 

SOR$_BADLOGIC Internal logic error detected. 

SOR$_ENDDIAGS Completed with diagnostics. 

SOR$_EXTEND Unable to extend work file for needed space. 

SOR$_MISS_PARAM A required subroutine argument is missing. 

SOR$_OPERFAIL Error requesting operator service. 

SOR$_OPREPLY Operator reply is ‘reply’. 

SOR$_READERR Error reading ‘file’. 

SOR$_REQ_ALT Specify alternate ‘name’ file (or nothing to simply 
try again). 

SOR$_RTNERROR Unexpected error status from user-written routine. 

SOR$_SORT_ON Sort or merge routines called in incorrect order. 

SOR$_SYSERROR System service error. 

SOR$_USE_ALT Using alternate file ‘name’. 

SOR$_WORK_DEV Work file ‘name’ must be on random access local 
device. 
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SORSSORT_MERGE Sort 


The SOR$SORT_MERGE routine sorts the input records. 





FORMAT 


SOR$SORT_MERGE [context] 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENT 


context 

VMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Value that distinguishes between multiple, concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT/MERGE 
routine for a particular sort or merge operation, the context longword must 
equal zero. SORT/MERGE then stores a value in the longword to identify 
the operation just initiated. When you make subsequent routine calls for the 
same operation, you must pass the context value supplied by SORT /MERGE. 





DESCRIPTION 


After you have passed either the file names or the records to SORT, call the 
SOR$SORT_MERGE routine to sort the records. For file interface on input, 
the input files are opened and the records are released to the sort. For the 
record interface on input, the record must have already been released (by 
calls to SOR$RELEASE_REC). For file interface on output, the output records 
are reformatted and directed to the output file. For the record interface on 
output, SORSRELEASE_—REC must be called to get the sorted records. 


Some of the return values are used with different severities depending on 
whether SORT/MERGE can recover. Thus, if you want to check for a specific 
status, you should use LIB; MATCH_COND. 





CONDITION 
VALUES 
RETURNED 


SOR-—44 


SS$_NORMAL Success. 
SOR$_BADDTYPE Invalid or unsupported CDD data type. 
SOR$_BADLENOFF Length and offset must be multiples of 8 bits. 


SOR$_BADLOGIC Internal logic error detected. 


SOR$_BADOCCURS 
SOR$_BADOVRLAY 
SOR$_BADPROTCL 

SOR$_BAD_LRL 


SOR$_BAD_TYPE 
SOR$_CDDERROR 
SOR$_CLOSEIN 
SOR$_CLOSEOUT 
SOR$_COL __CHAR 
SOR$_COL —CMPLX 
SOR$_COL _PAD 
SOR$_COL —THREE 
SOR$_ENDDIAGS 
SOR$_EXTEND 
SOR$_ILLBASE 
SOR$_ILLLITERL 
SOR$_ILLSCALE 
SOR$_INCDIGITS 


SOR$_INCNODATA 
SOR$_INCNOKEY 


SOR$_IND_OVR 
SOR$_KEYED 


SOR$_LRL—MISS 
SOR$_MISLENOFF 
SOR$_MULTIDIM 
SOR$_NOTRECORD 
SOR$_NO_WRK 


SOR$_OPENIN 
SOR$_OPENOUT 
SOR$_OPERFAIL 
SOR$S_OPREPLY 
SOR$_READERR 
SOR$_REQ —ALT 


SOR$_RTNERROR 
SOR$_SIGNCOMPQ 
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Invalid OCCURS clause. 
Invalid overlay structure. 
Node is an invalid CDD object. 


Record length n greater than longest specified 
record length. 


Invalid sort process specified. 

CDD error at node ‘name’. 

Error closing ‘file’ as input. 

Error closing ‘file’ as output. 

Invalid character definition. 

Collating sequence is too complex. 

Invalid pad character. 

Cannot define 3-byte collating values. 

Completed with diagnostics. 

Unable to extend work file for needed space. 
Nondecimal base is invalid. 

Record containing symbolic literals is unsupported. 
Nonzero scale invalid for floating-point data item. 


Number of digits is inconsistent with the type or 
length of item. 


Include specification references no ‘data’ keyword, 
at line n. 


Include specification references no ‘keys’ keyword, 
at line n. 


Indexed output file must already exist. 


Mismatch between SORT /MERGE keys and primary 
file key. 


Longest record length must be specified. 
Length and offset required. 

Invalid multidimensional OCCURS. 

Node ‘name’ is a name, not a record definition. 


Work files required, cannot do sort in memory as 
requested. 


Error opening ‘file’ as input. 

Error opening ‘file’ as output. 
Error requesting operator service. 
Operator reply is ‘reply’. 

Error reading ‘file’. 


Specify alternate ‘name’ file (or nothing to try 
again). 


Unexpected error status from user-written routine. 


Absolute Date and Time data type represented in 
one-second units. 
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SOR$_SORT_ON Sort or merge routines called in incorrect order. 

SOR$_SPCIVC Invalid collating sequence specification, at line n. 

SOR$_SPCIVD Invalid data type, at line n. 

SOR$_SPCIVF Invalid field specification, at line n. 

SOR$_SPCIVI Invalid include or omit specification, at line n. 

SOR$_SPCIVK Invalid key or data specification, at line n. 

SOR$_SPCIVP Invalid sort process, at line n. 

SOR$_SPCIVS Invalid specification, at line n. 

SOR$_SPCIVX Invalid condition specification, at line n. 

SOR$_SPCMIS Invalid merge specification, at line n. 

SOR$_SPCOVR "— Overridden specification, at line n. 

SOR$_SPCSIS Invalid sort specification, at line n. 

SORS$S_SRTIWA Insufficient space. Specification file is too complex. 

SOR$_SYSERROR System service error. 

SOR$S_UNSUPLEVL * Unsupported core level for record ‘name’. 

SOR$_USE_ALT Using alternate file ‘name’. 

SOR$S_WORK_DEV Work file ‘name’ must be on random access local 
device. 

SOR$_WRITEERR Error writing ‘file’. 
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SOR$SPEC_FILE Pass a Specification File Name 


The SOR$SPEC_FILE routine is used to pass a specification file or 
specification text to a sort or merge operation. 











FORMAT SORSSPEC_FILE /spec_file] [,spec_buffer] [, context] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS spec_tfile 
VMS usage: char_string 
type: character-coded text string 
access: read-only 


mechanism: by descriptor 


Specification file name. The spec_file argument is the address of a descriptor 
pointing to the name of a file that contains the text of the options requested 
for the sort or merge. The specification file name string and the specification 
file buffer arguments are mutually exclusive. 


spec_buffer 

VMS usage: char_string 
type: character-coded text string 
access: read-only 

mechanism: by descriptor 


Specification text buffer. The spec_buffer argument is the address of a 
descriptor pointing to a buffer containing specification text. This text has the 
same format as the text within the specification file. The specification file 
name string and the specification file buffer arguments are mutually exclusive. 


context 

VMS usage: context 

type: longword (unsigned) 
access: modify 


mechanism: by reference 


Value that distinguishes between multiple, concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT/MERGE 
routine for a particular sort or merge operation, the context longword must 
equal zero. SORT/MERGE then stores a value in the longword to identify 
the operation just initiated. When you make subsequent routine calls for the 
same operation, you must pass the context value supplied by SORT/MERGE. 
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SOR$SPEC_FILE 





DESCRIPTION 


Call SOR$SPEC_FILE to pass a specification file name or a buffer with 
specification text to a sort or merge operation. Through the use of a 
specification file, you may selectively omit or include particular records 
from the sort or merge operation and specify the reformatting of the output 
records. (See the Sort Utility in the VMS Sort/Merge Utility Manual for a 
complete description of specification files.) 


If you call the SOR$SPEC_FILE routine, you must do so before you call any 
other routines. You must pass either the spec_file or spec_buffer argument, 
but not both. 


Some of the return condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, if you want to 
check for a specific status, you should use LIBS] MATCH—COND. 





CONDITION | 
VALUES 
RETURNED 
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SOR$_ENDDIAGS Completed with diagnostics. 
SOR$_SORT_ON Sort or merge routine called in incorrect order. 
SOR$_SYSERROR System service error. 
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SORS$STAT Obtain a Statistic 


The SOR$STAT routine returns one statistic about the sort or merge 
operation to the user program. 





FORMAT 


SORS$STAT code , result [,context] 





RETURNS 
type: 
access: 


VMS usage: cond_value 
longword (unsigned) 
write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS code 
VMS usage: 
type: 
access: 
mechanism: 


word_unsigned 
word (unsigned) 
read only 

by reference 


SORT/MERGE statistic code. The code argument is the address of a word 
containing the code that identifies the statistic you want returned in the result 
argument. The following values are accepted. 


Code 


SOR$K_IDENT 
SOR$K_REC_INP 
SOR$K_REC_SOR 
SOR$K_REC_OUT 
SOR$K_LRL_INP 
SOR$K_LRL_INT 
SOR$K_LRL__OUT 
SOR$K_NODES 
SOR$K_INI_RUNS 
SOR$K_MRG_ORDER 
SOR$K_MRG_PASSES 
SOR$K_WRK_ALO 
SOR$K_MBC_INP 


Description 


Address of ASCII string for version number 


Number of records input 


Records sorted 


Records output 

Longest Record Length (LRL) for input 
Internal LRL 

LRL for output 

Nodes in sort tree 

Initial dispersion runs 

Maximum merge order 

Number of merge passes 

Work file allocation 

Multiblock count for input 
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Code Description 


SOR$K_MBC_OUT Multiblock count for output 
SORSK_MBF_INP Multibuffer count for input 
SOR$K_MBF_OUT Multibuffer count for output 


Note that performance statistics (such as direct 1/O, buffered I/O, and elapsed 
and CPU times) are not available because user-written routines may affect 
those values. However, they are available if you call LIB$GETJPI. 


result 


VMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


SORT/MERGE statistic value. The result argument is the address of a 
longword into which SORT/MERGE writes the value of the statistic identified 
by the code argument. 


context 


VMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Value that distinguishes between multiple, concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT/MERGE 
routine for a particular sort or merge operation, the context longword must | 
equal zero. SORT/MERGE then stores a value in the longword to identify 
the operation just initiated. When you make subsequent routine calls for the 
same operation, you must pass the context value supplied by SORT/MERGE. 





DESCRIPTION 


The SOR$STAT routine returns one statistic about the sort or merge operation 
to your program. You can call the SOR$STAT routine at any time while the 
sort or merge is active. 


Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, if you want to 
check for a specific status, you should use LIB, MATCH—COND. 





CONDITION 
VALUES 
RETURNED 
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SOR$_ENDDIAGS Completed with diagnostics. 
SOR$_MISS_PARAM A required subroutine argument is missing. 
SOR$_NYI . Functionality is not yet implemented. 
SOR$_SYSERROR System service error. 


1 3 VAX Text Processing Utility (VAXTPU) Routines 


13.1 Introduction to VAXTPU Routines 


This chapter describes callable VAX Text Processing (VAXTPU) Utility 
Routines. It describes the purpose of the VAXTPU callable routines, the 
parameters for the routine call, and the primary status returns. The parameter 
in the call syntax represents the object that you pass to a VAXTPU routine. 
Each parameter description lists the data type and the passing mechanism 
for the object. The data types are standard VMS data types. The passing 
mechanism indicates how the parameter list is interpreted. 


Callable VAXTPU Routines make VAXTPU accessible from within other VAX 
languages and applications. VAXTPU can be called from a program written in 
any VAX language that generates calls using the VAX Procedure Calling and 
Condition Handling Standard. You can also call VAXTPU from VMS utilities, 
for example, MAIL. Callable VAXTPU allows you to perform text processing 
functions within your program. 





Callable VAXTPU consists of a set of callable routines that resides in the 
VAXTPU shareable image, TPUSHR.EXE. You access callable VAXTPU by 
linking against this shareable image, which includes the callable interface 
routine names and constants. As with the DCL-level VAXTPU interface, you 
can use files for input to and output from callable VAXTPU. You can also 
write your own routines for processing file input, output, and messages. 


This chapter is written for system programmers who are assumed to be 
familiar with the following: 


e The VAX Procedure Calling and Condition Handling Standard 
e The VMS Run-Time Library (RTL) 


¢ The precise manner in which data types are represented on a VAX 
computer 


e The method for calling routines written in a language other than the one 
you are using for the main program 


The calling program must ensure that parameters passed to a called 
procedure, in this case VAXTPU, are of the type and form that the VAXTPU 
procedure accepts. 


The VAXTPU routines described in this chapter return condition values 
indicating the routine’s completion status. When comparing a returned 
condition value with a test value, you should use the LIBS5MATCH routine 
from the Run-Time Library. Do not test the condition value as if it were a 
simple integer. 
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13.1.1 Two Interfaces to Callable VAXTPU 


TPU-2 | 


There are two interfaces that you can use to access callable VAXTPU: the 
simplified callable interface and the full callable interface. 
Simplified Callable Interface 


The easiest way to use callable VAXTPU is to use the simplified callable 
interface. VAXTPU provides two alternative routines in its simplified callable 
interface. These routines in turn call additional routines that do the following: 


e Initialize the editor. 
e Provide the editor with the parameters necessary for its operation. 
¢ Control the editing session. 


¢ Perform error handling. 


When using the simplified callable interface, you can use the TPU$TPU_ 
routine to specify a VMS command line for VAXTPU, or you can call the 
TPU$EDIT routine to specify an input file and an output file. TPU$EDIT 
builds a command string that is then passed to the TPU$TPU routine. These 
two routines are described in detail in Section 13.2. 


Full Callable Interface 


To use the full callable interface, you have your program access the main 
callable VAXTPU routines directly. These routines do the following: 


e Initialize the editor (TPU$INTIALIZE). 


e Execute VAXTPU procedures (TPU$EXECUTE_INIFILE and 
TPU$EXECUTE_COMMAND). 


¢ Give control to the editor (TPUSCONTROL). 
e Terminate the editing session (TPU$CLEANUP). 


When using the full callable interface, you must provide values for certain 
parameters. In some cases, the values you supply are actually addresses 
for additional routines. For example, when you call TPU$INITIALIZE, you 
must include the address of a routine that specifies initialization options. 
Depending on your particular application, you may also have to write 
additional routines. For example, you may need to write routines for 
performing file operations, handling errors, and otherwise controlling the 
editing session. Callable VAXTPU provides utility routines that can perform 
some of these tasks for you. These utility routines can do the following: 


¢ Parse the VMS command line and build the item list used for initializing 
the editor. 


¢ Handle file operations. 
¢ Output error messages. 


e Handle conditions. 
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13.1.2 Shareable Image 


13.1 Introduction to VAXTPU Routines 


Various topics relating to the full callable interface are discussed in the 
following sections: 


e Section 13.3 begins by briefly describing the interface. However, 
most of this section describes the main callable VAXTPU routines 
(TPU$INITIALIZE, TPU$EXECUTE_INIFILE, TPU$CONTROL, 
TPU$EXECUTE_COMMAND, and TPU$CLEANUP). 


¢ Section 13.3.2 discusses additional routines that VAXTPU provides for use 
with the full callable interface. 


¢ Section 13.3.3 defines the requirements for routines that you can write for 
use with the full callable interface. 


The full callable interface consists of the main callable VAXTPU routines and 
the VAXTPU Utility routines. 


Whether you use the simplified callable interface or the full callable interface, 
you access callable VAXTPU by linking against the VAXTPU shareable image, 
TPUSHR.EXE. This image contains the routine names and constants available 
for use by an application. In addition, TPUSHR.EXE provides the following 
symbols: 


e TPU$VERSION—the version of the shareable image 
¢ TPU$UPDATE—the update number of the shareable image 


For more information about how to link to the shareable image TPUSHR.EXE, 
refer to the VMS System Services Reference Manual. 


13.1.3 Passing Parameters to Callable VAXTPU Routines 


Parameters are passed to callable VAXTPU by reference or by descriptor. 
When the parameter is a routine, the parameter is passed by descriptor as a 
bound procedure value (BPV) data type. 


A bound procedure value is a two-longword entity in which the first 
longword contains the address of a procedure entry mask, and the second 
longword is the environment value (see Figure 13-1). The environment 
value is determined in a language-specific manner when the original bound 
procedure value is generated. When the bound procedure is called, the calling 
program loads the second longword into R1. 
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13.1.4 Error Handling 


13.1.5 Return Values 


Figure 13—1 Bound Procedure Value 


NAME OF YOUR ROUTINE 


ENVIRONMENT | 


ZK-4046-85 





When you use the simplified callable interface, VAXTPU establishes its own 
condition handler, TPUSHANDLER, to handle all errors. When you use the 
full callable interface, there are two ways to handle errors: 


e You can use VAXTPU’s default condition handler, TRPUSHANDLER. 


e You can write your own condition handler to process some of the errors 
and call TPUSHANDLER to process the rest. 


The default condition handler, TPUSHANDLER, is described in the routine 
description section of this chapter. Information about writing your own 
condition handler can be found in the Introduction to VMS System Routines. 


All VAXTPU condition codes are declared as universal symbols. Therefore, 
you automatically have access to these symbols when you link your program 
to the shareable image. The condition code values are returned in RO. Return 
codes for VAXTPU can be found in the VAX Text Processing Utility Manual. 
VAXTPU return codes and their messages are included in the VMS System 
Messages and Recovery Procedures Reference Volume. 


Additional information about condition codes is provided in the descriptions 
of callable VAXTPU routines found in subsequent sections. This information 
is provided under the heading CONDITION VALUES RETURNED and 
indicates the values that are returned when the default condition handler is 
established. 


13.2 |The Simplified Callable Interface 
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The VAXTPU simplified callable interface consists of two routines: TPU$TPU 
and TPU$EDIT. These entry points to VAXTPU are useful for the following 
kinds of application: 


¢ Those able to specify all the editing parameters on a single command line 


e Those that need to specify only an input file and an output file - 
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13.2.1 Example of the Simplified Interface 


The following example shows how the simplified interface might be used to 
call VAXTPU. | 


/* Sample C program that calls VAXTPU. This program uses TPU$EDIT 
to provide the names of the input and output files, and TPU$TPU 
to pass a complete command line to the editor. */ 
#include descrip 
int return_status; 
char command_line [100]; 
static $DESCRIPTOR(input_file,"infile.dat") ; 
static $DESCRIPTOR(output_file,"outfile.dat") ; 
static $DESCRIPTOR (command_desc , command_line) ; 
static $DESCRIPTOR(first_part_desc , "EDIT/TPU/NOJOURNAL/NOCOMMAND/OUTPUT=") ; 
static $DESCRIPTOR(space_desc," "); 
main (argc,argv) 
int argc; 
char *argv[]; 


/* Call the routine that accepts the name of the input and output file. */ 
/* This passes the name of the input file and output file to VAXTPU. */ 
/* These values are made available to VAXTPU procedures for processing. */ 


return_status = TPU$EDIT(&input_file, £output_file) ; 
if (! return_status) 


exit (return_status) ; ‘ 


/* Now we build a command line and pass it to VAXTPU. */ 

/* Note that in this case we want to do more than just specify the */ 
/* file names. Our command also includes the /NOJOURNAL and /NOCOMMAND +*/ 
/* qualifiers. 


/* Concatenate all the command information into one string */ 


return_status = STR$CONCAT(&command_desc ,&first_part_desc,xoutput_file, 
&space_desc, &input_file) ; 
if (! return_status) 
exit (return_status) ; 

/* Now call VAXTPU */ 
return_status = TPU$TPU(&command_desc) ; 
exit (return_status) ; 


} 


The following section contains detailed information about the routines in 
the full VAXTPU callable interface. If you use the simplified interface, that 
interface calls these routines for you. If you use the full interface, your code 
calls these routines directly. 





13.3 The Full Callable Interface 


The VAXTPU full callable interface consists of a set of routines that you can 
use to perform the following tasks: 


e Specify initialization parameters. 
e¢ Control file input/output. 
e¢ Specify commands to be executed by the editor. 


e Control how conditions are handled. 5 
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When you use the simplified callable interface, these operations are performed 
automatically. The individual VAXTPU routines that perform these functions 
can be called from a user-written program and are known as VAXTPU’s full 
callable interface. This interface has two sets of routines: the main VAXTPU 
callable routines and the VAXTPU Utility routines. These VAXTPU routines, 
and your own routines that pass parameters to the VAXTPU routines, are the 
mechanism that your application uses to control VAXTPU. 


The following sections describe the main callable routines, how parameters 
are passed to these routines, the VAXTPU Utility routines, and the 
requirements of user-written routines. 


13.3.1 Main Callable VAXTPU Utility Routines 


Note: 


The following callable VAXTPU routines are described in this chapter: 
e TPUS$INITIALIZE 

e TPU$EXECUTE_INIFILE 

e TPU$CONTROL 

e TPU$SEXECUTE_COMMAND 

e TPU$SCLEANUP 


Before calling any of these routines, you must establish TPUSHANDLER 
or provide your own condition handler. See the routine description of 
TPU$SHANDLER at the end of this chapter and the “VAX Condition 
Handling Standard” in the Introduction to VMS System Routines for 
information about establishing a condition handler. 


13.3.2 Other VAXTPU Utility Routines 
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The full callable interface includes several utility routines for which you can 
provide parameters. Depending on your application, you may be able to use 
these routines rather than write your own routines. These VAXTPU Utility 
routines and their descriptions follow: 


e TPU$CLIPARSE—parses a command line and builds the item list for 
TPU$INITIALIZE 


e TPU$PARSEINFO—parses a command and builds an item list for 
TPUSINITIALIZE 


e TPU$FILEIO—the default file I/O routine 


¢ TPU$MESSAGE—writes error messages and strings using the built-in 
procedure MESSAGE 


e TPUSHANDLER—the default condition handler 


e TPU$CLOSE_TERMINAL—closes VAXTPU’s channel to the terminal 
(and its associated mailbox) for the duration of a CALL_USER routine 
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13.3.3 User-Written Routines 


13.4 


This section defines the requirements for user-written routines. When these 
routines are passed to VAXTPU, they must be passed as bound procedure 
values. (See Section 13.1.3 for a description of bound procedure values.) 
Depending on your application, you may have to write one or all of the 
following routines: 


¢ Routine for initialization callback—This is a routine that TPU$SINITIALIZE 
calls to obtain values for initialization parameters. If you choose to use 
TPU$INITIALIZE as a way of interfacing with VAXTPU, then you must 
write your own callback routine. This callback routine must call a parsing 
routine. The parsing routine can be TPU$CLIPARSE, or it can be a 
user-written routine. 


¢ Routine for file [/O—This is a routine that handles file operations. 
Instead of writing your own file I/O routine, you can use the 
TPU$FILEIO utility routine. VAXTPU does not use this routine for journal 
file operations or for operations performed by the built-in procedure 
SAVE. 


¢ Routine for condition handling—This is a routine that handles error 
conditions. Instead of writing your own condition handler, you can use 
the default condition handler, TPUSHANDLER. 


¢ Routine for the built-in procedure CALL_USER—This is a routine 
that is called by the built-in procedure CALL_USER. You can use this 
mechanism to cause your program to get control during an editing 
session. 





Examples of Using VAXTPU Routines 


Examples 13-1 through 13-4 use callable VAXTPU. The examples are 
included here for illustrative purposes only; DIGITAL does not assume 
responsibility for supporting these examples. 


Example 13-1 Sample VAX BLISS Template for Callable VAXTPU 


MODULE file_io_example (MAIN = top_level) = 


BEGIN 

FORWARD ROUTINE 
top_level, ! Main routine of this example 
tpu_init, ! Initialize TPU 
tpu_io; ! File I/0 routine for TPU 


! 
! Declare the stream data structure passed to the file I/O routine 
! 


MACRO 


stream_file_id = 0, 0, 32,0%, ! File ID 

stream_rat = 6, (0%. “85-0 hs ! Record attributes 
stream_rfm = 7,0, 8, O% ! Record format 
stream_file_nm = 8, 0, 0,04; ! File name descriptor 


Example 13-—1 Cont'd. on next page 


TPU-7 


VAX Text Processing Utility (VAXTPU) Routines 
13.4 Examples of Using VAXTPU Routines 


Example 13—1 (Cont.) Sample VAX BLISS Template for Callable VAXTPU 





These must be supplied 
in another module 


! 
! Declare the routines that would actually do the I/O. 
! 
! 


EXTERNAL ROUTINE 


my_io_open, 
my_io_close, 
my_io_get_record, 
my_io_put_record; — 


! Declare the VAXTPU routines 


EXTERNAL ROUTINE 


tpu$fileio, 
tpu$handler, 
tpu$initialize, 
tpu$execute_inifile, 
tpu$execute_command, 
tpu$control, 
tpu$cleanup; 


! Declare the VAXTPU literals 


EXTERNAL LITERAL 


tpu$k_close, 
tpu$k_close_delete, 
tpu$k_open, 
tpu$k_get, 
tpu$k_put, 


tpu$k_access, 
tpu$k_io, 
tpu$k_input, 
tpu$k_output, 


tpu$_calluser, 
tpu$_fileio, 
tpu$_outputfile, 
tpu$_sectionfile, 
tpu$_commandfile, 
tpu$_filename, 
tpu$_journalfile, 
tpu$_options, 


tpu$m_recover, 
tpu$m_journal, 
tpu$m_read, 
tpu$m_command, 
tpu$m_create, 
tpu$m_section, 
tpu$m_display, 
tpu$m_output, 


tpu$m_reset_terminal, 
tpu$m_kill_process, 
tpu$m_delete_exith, 
tpu$m_last_time, 


. 


Routine to open a file 
Routine to close a file 
Routine to read a record 
Routine to write a record 


VAXTPU's internal file I/O routine 
VAXTPU's condition handler 
Initialize VAXTPU 

Execute the initial procedures 
Execute a VAXTPU statement 

Let user interact with VAXTPU 

Have VAXTPU cleanup after itself 


File I/0 operation codes 


File access codes 


! Item list entry codes 


Mask for values in options bitvector 


Masks for cleanup bitvector 





Example 13-1 Cont'd. on next page 


TPU-8 


VAX Text Processing Utility (VAXTPU) Routines 
13.4 Examples of Using VAXTPU Routines 


Example 13—1 (Cont.) Sample VAX BLISS Template for Callable VAXTPU 





tpu$_nofileaccess, ! VAXTPU status codes 
tpu$_openin, 

tpu$_inviocode, 

tpu$_failure, 

tpu$_closein, 

tpu$_closeout, 

tpu$_readerr, 

tpu$_writeerr, 

tpu$_success; 


ROUTINE top_level = 
BEGIN 


{++ 
! Main entry point of your program 
{-- 


! Your_initialization_routine must be declared as a BPV 


LOCAL 
initialize_bpv: VECTOR [2], 
status, : 
cleanup_flags; 
! 
! First establish the condition handler 
! 
ENABLE 
tpu$handler (); 


! 
! Initialize the editing session, passing TPU$INITIALIZE the address of 
! the bound procedure value which defines the routine which VAXTPU is 

! to call to return the initization item list 

! 


initialize_bpv [0] = tpu_init; 

initialize_bpv [1] = 0; 

tpu$initialize (initialize_bpv) ; 

! 

! Call VAXTPU to execute the contents of the command file, the debug file 
! or the TPU$INIT_PROCEDURE from the section file. 

' ; 

tpu$execute_inifile() ; 

! 


! Let VAXTPU take over. 
' 


tpu$control () ; 
! 


! Have VAXTPU cleanup after itself 

! 

cleanup_flags = tpu$m_reset_terminal OR 
tpu$m_kill_process OR 
tpu$m_delete_exith OR 
tpu$m_last_time; 


Reset the terminal 

Delete Subprocesses 

Delete the exit handler 

Last time calling the editor 


tpu$cleanup (cleanup_flags) ; 
RETURN tpu$_success; 
END; 
ROUTINE tpu_init = 
BEGIN 





Example 13-1 Cont'd. on next page 
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Example 13—1 (Cont.) Sample VAX BLISS Template for Callable VAXTPU 


! Allocate the storage block needed to pass the file I/O routine as a 


! options 

OwN 

file_io_bpv: VECTOR [2, LONG] 
INITIAL (TPU_IO, 0), 


options; 
! 


! 
! 
! bound procedure variable as well as the bitvector for the initialization 
! 
! 


! These macros define the file names passed to VAXTPU 


! 
MACRO 


out_file = 'OUTPUT.TPU' % , 

com_file = 'TPU$COMMAND.TPU' % , 
sec_file = 'TPU$SECTION.TPU$SECTION' % , 
inp_file = 


‘FILE PU" 4% 


Create the item list to pass to VAXTPU. 


Each item list entry consists of 


two words which specify the size of the item and its code, the address of 
the buffer containing the data, and a longword to receive a result (always 
zero, since VAXTPU does not return any result values in the item list) 


Remember that the item list is always terminated with a longword containing 


a zero 


item_list = UPLIT BYTE ( 
WORD (4), 
WORD (tpu$_options) , 
LONG (options), 
LONG (0), 


WORD (4), 
WORD (tpu$_fileio), 
LONG (file_io_bpv) , 
LONG (0), 


WORD (%CHARCOUNT (out_file)), 
WORD (tpu$_outputfile) , 

LONG (UPLIT (%ASCII out_file)), 
LONG (0), 


WORD (%CHARCOUNT (com_file)), 
WORD (tpu$_commandfile), 

LONG (UPLIT (%ASCII com_file)), 
LONG (0), 
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WORD (%CHARCOUNT (sec_file)), 
WORD (tpu$_sectionfile), 

LONG (UPLIT (%ASCII sec_file)), 
LONG (0), 


WORD (%CHARCOUNT (inp_file)), 
WORD (tpu$_filename) , 

LONG (UPLIT (%ASCII inp_file)), 
LONG (0), 


LONG (0)); 
! 


! Initialize the options bitvector 

! 

options = tpu$m_display OR 
tpu$m_section OR 
tpu$m_create OR 


tpu$m_command OR 
tpu$m_output ; 


Sample VAX BLISS Template for Callable VAXTPU 


! Section file 


! Input file 


! Terminating longword of 0 


We have a display 

We have a section file 

Create a new file if one does not 
exist 

We have a section file 

We supplied an output file spec 


! Return the item list as the value of this routine for VAXTPU to interpret 


! 
RETURN item_list; 


END; 


! End of routine tpu_init 


ROUTINE tpu_io (p_opcode, stream: REF BLOCK [ ,byte], data) = 
! 


! This routine determines how to process a TPU I/0 request 


BEGIN 


LOCAL 
status; 


Is this one of ours, or do we pass it to TPU's file I/O routines? 


IF (..p_opcode NEQ tpu$k_open) AND (.stream [stream_file_id] GTR 511) 


THEN 


RETURN tpu$fileio (..p_opcode, .stream, .data); 


Either we're opening the file, or we know it's one of ours 
Call the appropriate routine (not shown in this example) 


SELECTONE ..p_opcode OF 
SET 


[tpu$k_open] : 


status = my_io_open (.stream, .data) ; 


{[tpu$k_close, tpu$k_close_delete] : 


status = my_io_close (.stream, .data); 


[tpu$k_get] : 


status = my_io_get_record (.stream, .data); 


{tpu$k_put] : 


status = my_io_put_record (.stream, .data) ; 
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Example 13—1 (Cont.) Sample VAX BLISS Template for Callable VAXTPU 


[OTHERWISE] : 
status = tpu$_failure; 
TES ; 
RETURN .status; 
END ; ! End of routine TPU_IO 
END ! End Module file_io_example 
ELUDOM 


Example 13-2 Normal VAXTPU Setup in VAX FORTRAN 


C A sample FORTRAN program that calls VAXTPU to act 
C normally, using the programmable interface. 
C 
C IMPLICIT NONE 
INTEGER*4 CLEAN_OPT foptions for clean up routine 
INTEGER*4 STATUS !return status from VAXTPU routines 
INTEGER*4 BPV_PARSE (2) !set up a Bound Procedure Value 
INTEGER*4 LOC_PARSE 'a local function call 
C declare the VAXTPU functions 
INTEGER*4 TPU$CONTROL 
INTEGER*4 TPU$CLEANUP 
INTEGER*4 TPU$EXECUTE_INIFILE 
INTEGER*4 TPU$INITIALIZE 
INTEGER*4 TPU$CLIPARSE 
C declare a local copy to hold the values of VAXTPU cleanup variables 
INTEGER*4 RESET_TERMINAL 
INTEGER*4 DELETE_JOURNAL 
INTEGER*4 DELETE_BUFFERS , DELETE_WINDOWS 
INTEGER*4 DELETE_EXITH, EXECUTE_PROC 
INTEGER*4 PRUNE_CACHE , KILL_PROCESSES 
INTEGER*4 CLOSE_SECTION 
C declare the VAXTPU functions used as external 
EXTERNAL TPU$HANDLER 
EXTERNAL TPU$CLIPARSE 
EXTERNAL TPU$_SUCCESS ‘external error message 
EXTERNAL LOC_PARSE user supplied routine to 
C call TPUCLIPARSE and setup 
C declare the VAXTPU cleanup variables as external these are the 
C external literals that hold the value of the options 
EXTERNAL TPU$M_RESET_TERMINAL 
EXTERNAL TPU$M_DELETE_ JOURNAL 
EXTERNAL TPU$M_DELETE_BUFFERS , TPU$M_DELETE_WINDOWS 
EXTERNAL TPU$M_DELETE_EXITH , TPU$M_EXECUTE_PROC 
EXTERNAL TPU$M_PRUNE_CACHE , TPU$M_KILL_PROCESSES 
100 CALL LIB$ESTABLISH ( TPU$HANDLER ) festablish the condition handler 
C set up the Bound Procedure Value for the call to TPU$INITIALIZE 
BPV_PARSE( 1 ) = %LOC( LOC_PARSE ) 
BPV_PARSE( 2 ) = 0 
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Example 13—2 (Cont.) Normal VAXTPU Setup in VAX FORTRAN 





C 


Q 


aqaaaa 


Qaa 


call the VAXTPU initialization routine to do some set up work 
STATUS = TPU$INITIALIZE ( BPV_PARSE ) 

Check the status if it is not a success then signal the error 
IF ( STATUS .NE. %4LOC ( TPU$_SUCCESS ) ) THEN 


CALL LIB$SIGNAL( %VAL( STATUS ) ) 
GOTO 9999 


ENDIF 
execute the TPU$_ init files and also a command file if it 
was specified in the command line call to VAXTPU 


STATUS = TPU$EXECUTE_INIFILE ( ) 
IF ( STATUS .NE. %LOC ( TPU$_SUCCESS ) ) THEN !make sure everything is ok 
CALL LIB$SIGNAL( %VAL( STATUS ) ) 


GOTO 9999 
ENDIF 
invoke the editor as it normally would appear 
STATUS = TPU$CONTROL ( ) 'call the VAXTPU editor 


IF ( STATUS .NE. %LOC ( TPU$_SUCCESS ) ) THEN !make sure everything is ok 


CALL LIB$SIGNAL( %VAL( STATUS ) ) 

GOTO 9999 
ENDIF 
Get the value of the option from the external literals. In FORTRAN you 
cannot use external literals directly so you must first get the value 
of the literal from its external location. Here we are getting the 
values of the options that we want to use in the call to TPU$CLEANUP. 


DELETE_ JOURNAL %LOC ( TPU$M_DELETE_JOURNAL ) 

DELETE_EXITH %LOC ( TPU$M_DELETE_EXITH ) 

DELETE_BUFFERS %LOC ( TPU$M_DELETE_BUFFERS ) 

DELETE_WINDOWS %LOC ( TPU$M_DELETE_WINDOWS ) 

EXECUTE_PROC %LOC ( TPU$M_EXECUTE_PROC ) 

RESET_TERMINAL *LOC ( TPU$M_RESET_TERMINAL ) 

KILL_PROCESSES %LOC ( TPU$M_KILL_PROCESSES ) 

CLOSE_SECTION %LOC ( TPU$M_CLOSE_SECTION ) 

Now that we have the local copies of the variables we can do the 
logical OR to set the multiple options that we need. 


CLEAN_OPT = DELETE_JOURNAL .OR. DELETE_EXITH .OR. 
1 DELETE_BUFFERS .OR. DELETE_WINDOWS .OR. EXECUTE_PROC 
1 .OR. RESET_TERMINAL .OR. KILL_PROCESSES .OR. CLOSE_SECTION 


do the necessary clean up 
TPU$CLEANUP wants the address of the flags as the parameter so 
pass the %LOC of CLEAN_OPT which is the address of the variable 


STATUS = TPU$CLEANUP ( %LOC ( CLEAN_OPT ) ) 
IF ( STATUS .NE. %LOC (TPU$_SUCCESS) ) THEN 

CALL LIB$SIGNAL( %VAL(STATUS) ) 
ENDIF 
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Example 13-2 (Cont.) Normal VAXTPU Setup in VAX FORTRAN 


9999 


9999 


CALL LIB$REVERT !go back to normal processing -- handlers 


STOP 
END 


INTEGER*4 FUNCTION LOC_PARSE 


INTEGER*4 BPV (2) !A local Bound Procedure Value 
CHARACTER*12 EDIT_COMM !A command line to send to TPU$CLIPARSE 
Declare the VAXTPU functions used 

INTEGER*+4 TPU$FILEIO 

INTEGER*4 TPU$CLIPARSE 


Declare this routine as external because it is never called directly and 
we need to tell FORTRAN that it is a function and not a variable 


EXTERNAL TPU$FILEIO 


BPV(1) = %LOC(TPU$FILEIO) 'set up the BOUND PROCEDURE VALUE 

BPV(2) = 0 

EDIT_COMM(1:12) = 'TPU TEST.TXT' 

parse the command line and build the item list for TPU$INITIALIZE 
LOC_PARSE = TPU$CLIPARSE (EDIT_COMM, BPV , 0) 


RETURN 
END 


Example 13-3 Building a Callback Item List with VAX FORTRAN 


Qaa 


QaQQ 


QaQaaQ 


PROGRAM TEST_TPU 
IMPLICIT NONE 
Define the expected VAXTPU return statuses 


EXTERNAL TPU$_SUCCESS 
EXTERNAL TPU$_QUITTING 


Declare the VAXTPU routines and symbols used 


EXTERNAL TPU$M_DELETE_CONTEXT 
EXTERNAL TPU$HANDLER 
INTEGER*4 TPU$M_DELETE_CONTEXT 
INTEGER*4 TPU$INITIALIZE 
INTEGER*4 TPU$EXECUTE_INIFILE 
INTEGER*4 TPU$CONTROL 
INTEGER*4 TPU$CLEANUP 


Declare the external callback routine 


EXTERNAL TPU_STARTUP ! the VAXTPU set-up function 
INTEGER*4 TPU_STARTUP 
INTEGER*4 BPV (2) ! Set up a bound procedure value 
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C 
C 
C 


QaaQaan QQQ aan aaa 


aan QagQ aaa 


QaQaa 


Declare the functions used for working with the condition handler 


INTEGER*4 LIB$ESTABLISH 
INTEGER*4 LIB$REVERT 


Local Flags and Indices 


INTEGER*4 CLEANUP_FLAG ! flag(s) for VAXTPU cleanup 
INTEGER*4 RET_STATUS 

Initializations 

RET_STATUS 0 


CLEANUP_FLAG %LOC (TPU$M_DELETE_CONTEXT) 
Establish the default VAXTPU condition handler 
CALL LIB$ESTABLISH (/REF (TPU$HANDLER) ) 


Set up the bound procedure value for the initialization callback 


BPV(1) 
BPV(2) 


%LOC (TPU_STARTUP) 
0 


Call the VAXTPU procedure for initialization 


RET_STATUS = TPU$INITIALIZE(BPV) 


IF (RET_STATUS .NE. %LOC(TPU$_SUCCESS)) THEN 
CALL LIB$SIGNAL (4VAL(RET_STATUS) ) 
ENDIF 


Execute the VAXTPU initialization file 


RET_STATUS = TPU$EXECUTE_INIFILE() 


IF (RET_STATUS .NE. %LOC(TPU$_SUCCESS) ) THEN 
CALL LIB$SIGNAL (4VAL(RET_STATUS) ) 
ENDIF 


Pass control to VAXTPU 


RET_STATUS = TPU$CONTROL() 


IF (RET_STATUS .NE. %LOC(TPU$_QUITTING) 

1 .OR. %LOC(TPU$_QUITTING)) THEN 
CALL LIB$SIGNAL ({%VAL(RET_STATUS) ) 

ENDIF 


Clean up after processing 


RET_STATUS = TPU$CLEANUP ((%REF (CLEANUP_FLAG) ) 


IF (RET_STATUS .NE. “%LOC(TPU$_SUCCESS)) THEN 
CALL LIB$SIGNAL (4VAL(RET_STATUS) ) 
ENDIF 
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Example 13-3 (Cont.) Building a Callback Item List with VAX FORTRAN 


C 
C 
C 


Qaan 


Qaa 


Qan 


QaQQ QaQ QaQQ 


QaQaa 


Set the condition handler back to the default 


RET_STATUS = LIB$REVERT () 
END 


INTEGER*4 FUNCTION TPU_STARTUP 
IMPLICIT NONE 


INTEGER*4 OPTION_MASK ! temporary variable for VAXTPU 
CHARACTER*+44 SECTION_NAME ! temporary variable for VAXTPU 


External VAXTPU routines and symbols 


EXTERNAL TPU$K_OPTIONS 
EXTERNAL TPU$M_READ 
EXTERNAL TPU$M_SECTION 
EXTERNAL TPU$M_DISPLAY 
EXTERNAL TPU$K_SECTIONFILE 
EXTERNAL TPU$K_FILEIO 
EXTERNAL TPU$FILEIO 
INTEGER*4 TPU$FILEIO 


The bound procedure value used for setting up the file I/O routine 


INTEGER*4 BPV (2) 


Define the structure of the item list defined for the callback 


STRUCTURE /CALLBACK/ 


INTEGER*2 BUFFER_LENGTH 
INTEGER*2 ITEM_CODE 

INTEGER*4 BUFFER_ADDRESS 
INTEGER*4 RETURN_ADDRESS 


END STRUCTURE 

There are a total of four items in the item list 

RECORD /CALLBACK/ CALLBACK (4) 

Make sure it is not optimized! 

VOLATILE /CALLBACK/ 

Define the options we want to use in the VAXTPU session 


OPTION_MASK = %LOC(TPU$M_SECTION) .OR. %LOC(TPU$M_READ) 
f .OR. %LOC(TPU$M_DISPLAY) 


Define the name of the initialization section file 


SECTION_NAME = ‘device: [user] TPUSECTION.TPU$SECTION' 
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Set up the required I/O routine. Use the VAXTPU default. 


BPV(1) 
BPV (2) 


4LOC (TPU$F ILEIO) 
0 


Build the callback item list 
Set up the edit session options 


CALLBACK (1) .ITEM_CODE = %LOC(TPU$K_OPTIONS) 
CALLBACK (1) .BUFFER_ADDRESS = %LOC (OPTION_MASK) 
CALLBACK (1) .BUFFER_LENGTH = 
CALLBACK (1) .RETURN_ADDRESS = 0 


Identify the section file to be used 


CALLBACK (2) . ITEM_CODE = %LOC(TPU$K_SECTIONF ILE) 
CALLBACK (2) .BUFFER_ADDRESS = %LOC(SECTION_NAME) 
CALLBACK (2) .BUFFER_LENGTH = LEN(SECTION_NAME) 
CALLBACK (2) .RETURN_ADDRESS = 0 


Set up the I/O handler 


CALLBACK (3) .ITEM_CODE = 4LOC (TPU$K_FILEIO) 
CALLBACK (3) .BUFFER_ADDRESS = %LOC(BPV) 
CALLBACK (3) .BUFFER_LENGTH = 4 
CALLBACK (3) .RETURN_ADDRESS = 0 


End the item list with zeros to indicate we are finished 


CALLBACK (4) .ITEM_CODE = 0 

CALLBACK (4) .BUFFER_ADDRESS = 0 
CALLBACK (4) .BUFFER_LENGTH = 0 
CALLBACK (4) .RETURN_ADDRESS = 0 


Return the address of the item list 


TPU_STARTUP = %LOC (CALLBACK) 


RETURN 
END 


Building a Callback Item List with VAX FORTRAN 
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Example 13-4 Specifying a User-Written File |/O Routine in VAX C 





/* 

Simple example of a C program to invoke TPU. This program provides its 
own FILEIO routine instead of using the one provided by TPU. 

*/ 

#include descrip 

#include stdio 


/* data structures needed */ 


struct bpv_arg /* bound procedure value */ 
int *routine_add ; /* pointer to routine */ 
int env ; /* environment pointer */ 
Py 
struct item_list_entry /* item list data structure */ 
{ 
short int buffer_length; /* buffer length */ 
short int item_code; /* item code */ 
int *buffer_add; /* buffer address */ 
int *return_len_add; /* return address */ 
5 
struct stream_type 
{. 
int ident; /* stream id */ 
short int alloc; /* file size */ 
short int flags; /* file record attributes/format */ 
short int length; /* resultant file name length */ 
short int stuff; /* file name descriptor class & type */ 
int nam_add; /* file name descriptor text pointer */ 
rs 
globalvalue tpu$_success; /* TPU Success code */ 
globalvalue tpu$_quitting; /* Exit code defined by TPU */ 
globalvalue /* Cleanup codes defined by TPU */ 


tpu$m_delete_journal, tpu$m_delete_exith, 
tpu$m_delete_buffers, tpu$m_delete_windows, tpu$m_delete_cache, © 
tpu$m_prune_cache, tpu$m_execute_file, tpu$m_execute_proc, 
tpu$m_delete_context, tpu$m_reset_terminal, tpu$m_kill_processes, 
tpu$m_close_section, tpu$m_delete_others, tpu$m_last_time; 
globalvalue /* Item codes for item list entries */ 
tpu$k_fileio, tpu$k_options, tpu$k_sectionfile, 
tpu$k_commandfile ; 
globalvalue /* Option codes for option item */ 
tpu$m_display, tpu$m_section, tpu$m_command, tpu$m_create ; 


globalvalue /* Possible item codes in item list */ 
tpu$k_access, tpu$k_filename, tpu$k_defaultfile, 
tpu$k_relatedfile, tpu$k_record_attr, tpu$k_maximize_ver, 
tpu$k_flush, tpu$k_filesize; 


globalvalue /* Possible access types for tpu$k_access */ 
tpu$k_io, tpu$k_input, tpu$k_output; . 

globalvalue /* RMS File Not Found message code */ 
rms$_fnf ; 
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globalvalue /* FILEIO routine functions */ 
tpu$k_open, tpu$k_close, tpu$k_close_delete, 
tpu$k_get, tpu$k_put; 


int lib$establish (); /* RTL routine to establish an event handler */ 
int tpu$cleanup (); /* TPU routine to free resources used */ 

int tpu$control (); /* TPU routine to invoke the editor */ 

int tpu$execute_inifile (); /* TPU routine to execute initialization code */ 
int tpu$handler (); /* TPU signal handling routine */ 

int tpu$initialize (); /* TPU routine to initialize the editor */ 

/* 


This function opens a file for either read or write access, based upon 

the itemlist passed as the data parameter. Note that a full implementation 
of the file open routine would have to handle the default file, related 
file, record attribute, maximize version, flush and file size item code 


properly. 

*/ 
open_file (data, stream) 
int *data; 
struct stream_type *stream; 
a! 

struct item_list_entry *item; 

char *access; /* File access type */ 

char filename [256] ; /* Max file specification size */ 


FILE *fopen(); 
/* Process the item list */ 


item = data; 
while (item->item_code != 0 && item->buffer_length != 0) 


1 

if (item->item_code == tpu$k_access) 
{ 
if (item->buffer_add == tpu$k_io) access = "r+"; 
else if (item->buffer_add == tpu$k_input) access = "r"; 
else if (item->buffer_add == tpu$k_output) access = "w"; 
} 

else if (item->item_code == tpu$k_filename) 
{ 


strncpy (filename, item->buffer_add, item->buffer_length) ; 
filename [item->buffer_length] = 0; 
lib$scopy_r_dx (&item->buffer_length, item->buffer_add, 
&stream->length) ; 
} 
else if (item->item_code == tpu$k_defaultfile) 


{ /* Add code to handle default file */ 

} /* spec here */ 
else if (item->item_code == tpu$k_relatedfile) 

{ /* Add code to handle related */ 

} /* file spec here */ 
else if (item->item_code == tpu$k_record_attr) 

{ /* Add code to handle record */ 

By /* attributes for creating files * / 
else if (item->item_code == tpu$k_maximize_ver) 

{ /* Add code to maximize version . */ 

} /* number with existing file here +*/ 
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Example 13—4 (Cont.) Specifying a User-Written File 1/O Routine in VAX C 


else if (item->item_code == tpu$k_flush) 


{ /* Add code to cause each record */ 
} /* to be flushed to disk as written */ 
else if (item->item_code == tpu$k_filesize) 
{ /* Add code to handle specification */ 
} _/* of initial file allocation here +*/ 
++item; /* get next item */ 
} ; 
stream->ident = fopen(filename, access) ; 
if (stream->ident != 0) 
“return tpu$_success; 
else 
return rms$_fnf ; 
} 
/* 
This procedure closes a file 
*/ 


close_file (data,stream) 
struct stream_type *stream; 


{ 
close(stream->ident) ; 
return tpu$_success; 
} 
/* 
This procedure reads a line from a file 
*/ 
read_line(data, stream) 
struct dsc$descriptor *data; 
struct stream_type *stream; 


{ 
char textline [984]; /* max line size for TPU records */ 
int len; 


globalvalue rms$_eof; /* RMS End-Of-File code */ 


if (fgets (textline,984,stream->ident) == NULL) 
return rms$_eof ; 
else 
a! 
len = strlen(textline) ; 
if (len > 0) 
len = len - 1; 
return lib$scopy_r_dx (&len, textline, data); 
iG 
} 
/* 
This procedure writes a line to a file 
*/ 
write_line(data, stream) 
struct dsc$descriptor *data; 
struct stream_type *stream; 


{ 


char textline [984] ; /* max line size for TPU records */ 
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Example 13—4 (Cont.) Specifying a User-Written File |/O Routine in VAX C 





strncpy (textline, data->dsc$a_pointer, data->dsc$w_length) ; 
textline [data->dsc$w_length] = 0; 
fputs(textline,stream->ident) ; 

fputs("\n" ,stream->ident) ; 

return tpu$_success; 


} 
/* 
This procedure will handle I/O for TPU 
*/ 
fileio(code,stream,data) 
int *code; 
int *stream; 
int *data; 
{ 
int status; 
/* Dispatch based on code type. Note that a full implementation of the */ 
/* file I/O routines would have to handle the close and delete code properly */ 
/* instead of simply closing the file */ 
if (*code == tpu$k_open) /* Initial access to file */ 
status = open_file (data,stream) ; 
else if (*code == tpu$k_close) /* End access to file */ 
status = close_file (data,stream) ; 
else if (*code == tpu$k_close_delete) /* Treat same as close */ 
status = close_file (data,stream) ; 
else if (*code == tpu$k_get) /* Read a record from a file */ 
status = read_line (data,stream) ; 
else if (*code == tpu$k_put) /* Write a record to a file */ 
status = write_line (data,stream) ; 
else 
« /* Who knows what we got? */ 
status = tpu$_success; 
printf ("Bad FILEIO I/O function requested") ; 
Bs 
return status; 
} 
/* 
This procedure formats the initialization item list and returns it as 
is return value. 
* / 
callrout () 
a 


static struct bpv_arg add_block = 
{ fileio, 0} ; /* BPV for fileio routine */ 
int options ; 
char *section_name = "TPUSECINI"; 
static struct item_list_entry arg[] = 


{/* length code buffer add return add */ 
{ 4,tpu$k_fileio, 0, 0}, 
{ 4,tpu$k_options, 0, O35 
{ 0,tpu$k_sectionfile,0O, 0 }, 
{ 0,0, 0, - 0 } 
3; 
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/* Setup file I/O routine item entry */ 
arg[0].buffer_add = &add_block; 


/* Setup options item entry. Leave journaling off. */ 
options = tpu$m_display | tpu$m_section; 
arg[1].buffer_add = &options; 


/* Setup section file name */ 
arg(2].buffer_length = strlen(section_name) ; 
arg([2] .buffer_add = section_name; 


return arg; 


} 
/* 


Main program. Initializes TPU, then passes control to it. 
*/ 
main () 
{ 
int return_status ; 
int cleanup_options; 
struct bpv_arg add_block; 


/* Establish as condition handler the normal VAXTPU handler */ 
lib$establish(tpu$handler) ; 
/* Setup a BPV to point to the callback routine */ j 


add_block.routine_add = callrout ; 
add_block.env = 0; 


/* Do the initialize of VAXTPU */ 


return_status = tpu$initialize(&add_block) ; 
if (!return_status) 
exit (return_status) ; 


/* Have TPU execute the procedure TPU$INIT_PROCEDURE from the section file */ 
/* and then compile and execute the code from the command file */ 


return_status = tpu$execute_inifile() ; 
if (!return_status) 
exit (return_status) ; 


/* Turn control over to VAXTPU */ 


return_status = tpu$control (); 
if (!return_status) 
exit (return_status) ; 


/* Now clean up. */ 


cleanup_options = tpu$m_last_time | tpu$m_delete_context; 
return_status = tpu$cleanup (&cleanup_options) ; 
exit (return_status) ; 


printf ("Experiment complete") ; 
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13.5 VAXTPU Routines 
The following pages describe the individual VAXTPU routines. 
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TPUSCLEANUP Free System Resources Used 
During VAXTPU Session 


The TPUSCLEANUP routine cleans up internal data structures, frees 
memory, and restores terminals to their initial state. 


This is the final routine called in each interaction with VAXTPU. 








FORMAT TPUSCLEANUP flags 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. The condition value that this routine can return is listed under 
CONDITION VALUE RETURNED. 





ARGUMENT flags 


VMS usage: mask_longword 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Flags (or mask) defining the cleanup options. The flags argument is the 
address of a longword bit mask defining the cleanup options or the address 
of a 32-bit mask defining the cleanup options. This mask is the logical 
OR of the flag bits you want to set. TPU$V ... indicates a bit item and 
TPUS$M ... indicates a mask. Following are the various cleanup options. 


Symbol!' Function 


TPU$M_DELETE_JOURNAL Closes and deletes the journal file if it is open. 
TPUSM_DELETE_EXITH Deletes VAXTPU's exit handler. 


TPUSM_DELETE_BUFFERS Deletes all text buffers. If this is not the last 
time you are calling VAXTPU, then all variables 
referring to these data structures are reset, as if 
by the built-in procedure DELETE. If a buffer is 
deleted, then all ranges and markers within that 
buffer, and any subprocesses using that buffer, | 
are also deleted. 


'The prefix can be TPU$M_ or TPU$V_. TPU$SM_ denotes a mask corresponding to the 
specific field in which the bit is set. TPU$V_ is a bit number. 
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Symbol! 
TPU$M_DELETE_WINDOWS 


TPUSM_DELETE__CACHE 


TPUSM_—PRUNE_CACHE 


TPU$M_EXECUTE_FILE 


TPUSM_EXECUTE_PROC 


TPUSM_DELETE_CONTEXT 


TPUSM_RESET_TERMINAL 


TPUSM_KILL__PROCESSES 


TPU$SM_CLOSE_SECTION? 


TPUSCLEANUP 


Function 


Deletes all windows. If this is not the last 

time you are calling VAXTPU, then all variables 
referring to these data structures are reset, as if 
by the built-in procedure DELETE. 


Deletes the virtual file manager's data structures 
and caches. If this deletion is requested, then all 
buffers are also deleted. If the cache is deleted, 
the initialization routine has to reinitialize the 
virtual file manager the next time it is called. 


Frees up any virtual file manager caches that 
have no pages allocated to buffers. This frees 
up any caches that may have been created 
during the session but are no longer needed. 


Reexecutes the command file if 
TPUSEXECUTE_INIFILE is called again. You 
must set this bit if you plan to specify a new 
file name for the command file. This option is 
used in conjunction with the option bit passed 
to TPU$INITIALIZE indicating the presence of 
the /COMMAND qualifier. 


Looks up TPUSINIT_PROCEDURE and executes 
it the next time TPUSEXECUTE_INIFILE is © 
called. 


Deletes the entire context of VAXTPU. If this 
option is specified, then all other options are 
implied, except for executing the initialization file 
and initialization procedure. 


Resets the terminal to the state it was in 
upon entry to VAXTPU. The terminal mailbox 
and all windows are deleted. If the terminal 
is reset, then it is reinitialized the next time 
TPUS$INITIALIZE is called. 


Deletes all subprocesses created during the 
session. 


Closes the section file and releases the 
associated memory. All buffers, windows, 

and processes are deleted. The cache is purged 
and the flags are set for reexecution of the 
initialization file and initialization procedure. 

If the section is closed and if the option bit 
indicates the presence of the SECTION qualifier, 
then the next call to TPUSINITIALIZE attempts a 
new restore operation. 


1The prefix can be TPU$M_ or TPU$SV_. TPU$SM_ denotes a mask corresponding to the 
specific field in which the bit is set. TPU$V_ is a bit number. 


2Using the simplified callable interface does not set TPU$_CLOSE_SECTION. This feature 
allows you to make multiple calls to TPUSTPU without requiring you to open and close the 


section file on each call. 
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TPUSCLEANUP 
Symbol! Function 
TPUSM__DELETE_OTHERS Deletes all miscellaneous preallocated data 

structures. Memory for these data structures 
is reallocated the next time TPUSINITIALIZE is 
called. 

TPUSM_LAST_TIME This bit should be set only when you are calling 
VAXTPU for the last time. Note that if you set 
this bit and then recall VAXTPU, the results are 
unpredictable. 

1The prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask corresponding to the 

specific field in which the bit is set. TPU$V_ is a bit number. 

DESCRIPTION The cleanup routine is the final routine called in each interaction with 
VAXTPU. It tells VAXTPU to clean up its internal data structures and prepare 
for additional invocations. You can control what is reset by this routine by 
setting or clearing the flags described previously. 

When you finish with VAXTPU, call this routine to free the memory and 

restore the characteristics of the terminal to their original settings. 

If you intend to exit after calling TPUS$CLEANUP, do not delete the data 

structures; VMS does this automatically. Allowing VMS to delete the 
structures improves the performance of your program. 

Notes 

1 When you use the simplified interface, VAXTPU automatically sets the 

following flags: 

e TPU$V_RESET_TERMINAL 

e TPU$V_DELETE_BUFFERS 
e TPU$V_DELETE_JOURNAL 
e TPU$V_DELETE_WINDOWS 
e TPU$V_DELETE_EXITH 

e¢ TPU$V_EXECUTE_PROC 

e TPU$V_EXECUTE_FILE 

e¢ TPU$V_PRUNE—CACHE 

e TPU$V_KILL_PROCESSES 

2. If this routine does not return a success status, no other calls to the editor 

should be made. 

CONDITION TPU$_SUCCESS N | ful leti 

VALUE = ormal successful completion. 

RETURNED 
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TPUSCLIPARSE 


TPUSCLIPARSE Parse a Command Line 


The TPU$CLIPARSE routine parses a command line and builds the item list 


for TPUSINITIALIZE. 


It calls CLISDCL__PARSE to establish a command table and a command 
to parse. It then calls TPUSPARSEINFO to build an item list for 
TPUSINITIALIZE. 











FORMAT TPUSCLIPARSE | string, fileio, call_user 
RETURNS VMS usage: item_list 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

This routine returns the address of an item list. 
ARGUMENTS string 

VMS usage: char_string 

type: character string 

access: read only 


mechanism: by descriptor 


Command line. The string argument is the address of a descriptor of a 
VAXTPU command. 


fileio 

VMS usage: vector_longword_unsigned 
type: bound procedure value 
access: read only 


mechanism: by descriptor 


File I/O routine. The fileio argument is the address of a descriptor of a file 
I/O routine. ; 


call_user 

VMS usage: vector_longword_unsigned 
type: bound procedure value 
access: read only 

mechanism: by descriptor 


Call-user routine. The call_user argument is the address of a descriptor of a 
call-user routine. 
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TPUSCLOSE_TERMINAL Close Channel to 
Terminal 


The TPU$CLOSE_TERMINAL routine closes VAXTPU’s channel to the 
terminal. 


FORMAT TPU$SCLOSE_TERMINAL 








RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. The condition value that this routine can return is listed under 
CONDITION VALUE RETURNED. 





ARGUMENTS ~ None. 





DESCRIPTION _sThis routine is used with the built-in procedure CALL_USER and its 
associated call-user routine to control VAXTPU’s access to the terminal. 
When a call-user routine invokes TPU$CLOSE_TERMINAL, VAXTPU closes 
its channel to the terminal and the channel of VAXTPU’s associated mailbox. 


When the call-user routine returns control to it, VAXTPU automatically 
reopens a channel to the terminal and redisplays the visible windows. 


A call-user routine can use TPU$CLOSE_TERMINAL at any point in the 
program and as many times as necessary. If the terminal is already closed to 
VAXTPU when TPU$CLOSE_TERMINAL is used, the call is ignored. 





CONDITION | 
VALUE TPU$_SUCCESS Normal successful completion. 


RETURNED 
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TPUSCONTROL Pass Control to VAXTPU 


The TPU$CONTROL routine is the main processing routine of the VAXTPU 
editor. It is responsible for reading the text and commands, and executing 
them. When you call this routine (after calling TPUSINITIALIZE), control is 
turned over to VAXTPU. 








FORMAT TPUSCONTROL 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS _~_ None. 





DESCRIPTION This routine controls the editing session. It is responsible for reading the text 
and commands and for executing them. Windows on the screen are updated 
to reflect the edits made. 


Note: Control is returned to your program only if an error occurs or after you 
enter either the built-in procedure QUIT or the built-in procedure EXIT. 





CONDITION TPU$_EXITING A result of EXIT (when the default conditi 

2 result o when the default condition 
VALUES handler is established). 
RETURNED TPU$_QUITTING A result of QUIT (when the default condition 


handler is established). 
TPU$_RECOVERFAIL A recovery operation was terminated abnormally. 
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TPUSEDIT 


Edit a File 


The TPU$EDIT routine builds a command string from its parameters and 
passes it to the TPU$TPU routine. 


TPUSEDIT is another entry point to VAXTPU’s simplified callable interface. 














FORMAT TPUS$EDIT input, output 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS input 
VMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 
Input file name. The input argument is the address of a descriptor of a file 
specification. 
output 
VMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 
Output file name. The output argument is the address of a descriptor of an 
output file specification. It is used with the /OUTPUT command qualifier. 
DESCRIPTION ss This routine builds a command string and passes it to TPU$TPU. If the length 
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of the output string is greater than 0, you can include it in the command line 
using the /OUTPUT qualifier, as follows: 


TPU [/OUTPUT= output] input 


If your application parses information that is not related to the operation 
of VAXTPU, make sure the application obtains and uses all non-VAXTPU 
parse information before the application calls TPU$EDIT. The reason is 
that TPU$EDIT destroys all parse information obtained and stored before 
TPUSEDIT is called. , 
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TPUSEDIT 





CONDITION This routine returns any value returned by TPUSTPU. 
VALUES 


RETURNED 
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TPUSEXECUTE_COMMAND Execute One or __ 


More VAXTPU 
Statements 


The TPUSEXECUTE_COMMAND routine allows your program to execute 
VAXTPU statements. 

















FORMAT TPUSEXECUTE_COMMAND string 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 
ARGUMENT string 
VMS usage: char_string 
type: ' character string 
access: read only 
mechanism: by value 
VAXTPU statement. The string argument is the address of a descriptor of a 
character string denoting one or more VAXTPU statements. 
DESCRIPTION This routine performs the same function as the built-in procedure EXECUTE 
described in the VAX Text Processing Utility Manual. 
CONDITION TPU$_SUCCESS N | ful leti 
= tion. 
VALUES TPU$_EXITING aes a oy - ked 
RETURNED Pal ullt-IN procedure was Invoked. 
TPU$_QUITTING QUIT built-in procedure was invoked. 
TPU$_EXECUTEFAIL Execution aborted. This could be because of 
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TPUSEXECUTE_INIFILE Execute Initialization 
Files 


The TPU$EXECUTE_INIFILE routine allows you to execute a user-written 
initialization file. 


This routine must be executed after the editor is initialized, but before any 
other commands are processed. 








FORMAT TPUSEXECUTE_INIFILE 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS ~ None. 





DESCRIPTION Calling the TPU$EXECUTE_INIFILE routine causes VAXTPU to perform the 
following steps: 


1 The command file is read into a buffer. The default is 
TPU$COMMAND.TPU. If you specified a file on the command line 
that cannot be found, an error message is displayed and the routine is 
aborted. 


2 If you specified the /DEBUG qualifier on the command line, the DEBUG 
file is read into a buffer. The default is SYS$SHARE:TPU$DEBUG.TPU. 


The DEBUG file is compiled and executed (if available). 
TPUS$INIT_PROCEDURE is executed (if available). 

The Command buffer is compiled and executed (if available). 
6 TPUSINIT_POSTPROCEDURE is executed (if available). 


of W 


Note: If you call this routine after calling TPU$CLEANUP, you must set 
the flags TPU$_EXECUTEPROCEDURE and TPU$_EXECUTEFILE. 
Otherwise, the initialization file does not execute. 
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TPUSEXECUTE_INIFILE 





CONDITION 
VALUES TPU$_SUCCESS 
RETURNED TPU$_EXITING 


TPU$S_QUITTING 


TPU$_COMPILEFAIL 


TPUS_EXECUTEFAIL 


TPU$_FAILURE 
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Normal successful completion. 


A result of EXIT. If the default condition handler is 
being used, the session is terminated. 


A result of QUIT. If the default condition handler is 
being used, the session is terminated. 


The compilation of the initialization file was 
unsuccessful. 


The execution of the statements in the initialization 
file was unsuccessful. 


General code for all other errors. 
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TPU$FILEIO Perform File Operations 


The TPU$FILEIO routine handles all VAXTPU file operations. Your own 
file |/O routine can call this routine to perform some operations for it. 
However, the routine that opens the file must perform ai/ operations for 
that file. For example, if TPUSFILEIO opens the file, it must also 

close it. 











FORMAT TPUS$FILEIO code, stream, data 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS code 
VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


Item code specifying a VAXTPU function. The code argument is the address 
of a longword containing an item code from VAXTPU specifying a function 
to perform. Following are the item codes that you can specify in the file I/O 
routine: 


¢ TPU$K_OPEN—This item code specifies that the data parameter is 
the address of an item list. This item list contains the information 
necessary to open the file. The stream parameter should be filled in 
with a unique identifying value to be used for all future references to this 
file. The resultant file name should also be copied with a dynamic string 
descriptor. 


e TPU$K_CLOSE—The file specified by the stream argument is to be 
closed. All memory being used by its structures can be released. 


e TPU$K_CLOSE_DELETE—The file specified by the stream argument is 
to be closed and deleted. All memory being used by its structures can be 
released. 


¢ TPU$K_GET—The data parameter is the address of a dynamic string 
descriptor to be filled with the next record from the file specified by 
the stream argument. The routine should use the routines provided by 
the VMS Run-Time Library to copy text into this descriptor. VAXTPU 
frees the memory allocated for the data read when the file I/O routine 
indicates that the end of the file has been reached. 
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e TPU$K_PUT—The data parameter is the address of a descriptor for the 
data to be written to the file specified by the stream argument. 


stream 

VMS usage: unspecified 

type: longword (unsigned) 
access: modify 


mechanism: by reference 


File description. The stream argument is the address of a data structure 
consisting of four longwords. This data structure is used to describe the file to 
be manipulated. 


This data structure is used to refer to all files. It is written to when an open 
file request is made. All other requests use information in this structure to 
determine which file is being referenced. 


Figure 13-2 shows the stream data structure. 


Figure 13—2 Stream Data Structure 


[ow [ sero 
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The first longword is used to hold a unique identifier for each file. The user- 
written file I/O routine is restricted to values between 0 and 511. Thus, you 
can have up to 512 files open simultaneously. 


The second longword is divided into three fields. The low word is used to 
store the allocation quantity, that is, the number of blocks allocated to this 
file from the FAB (FAB$L__ALQ). This value is used later to calculate the 
output file size for preallocation of disk space. The low-order byte of the 
second word is used to store the record attribute byte (FAB$B_RAT) when an 
existing file is opened. The high-order byte is used to store the record format 
byte (FAB$B_RFM) when an existing file is opened. The values in the low 
word and the low-order and high-order bytes of the second word are used for 
creating the output file in the same format as the input file. These three fields 
are to be filled in by the routine opening the file. 


The last two longwords are used as a descriptor for the resultant or the 
expanded file name. This name is used later when VAXTPU processes EXIT 
commands. This descriptor is to be filled in with the file name after an open 
operation. It should be allocated with either the routine LIB{SCOPY_R_DX 
or the routine LIB$SCOPY_DX from the Run-Time Library. This space is 
freed by VAXTPU when it is no longer needed. 
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Note: 


TPUS$FILEIO 
data 
VMS usage: item_list_3 
type: longword (unsigned) 
access: modify 


mechanism: by reference 


Stream data. The data argument is either the address of an item list or the 
address of a descriptor. 


The meaning of this parameter depends on the item code specified in the 
code field. 


When the TPU$K_OPEN item code is issued, the data parameter is the 
address of an item list containing information about the open request. The 
following VAXTPU item codes are available for specifying information about 
the open request: 


TPU$K_ACCESS item code allows you to specify one of three item codes 
in the buffer address field, as follows: 


- TPU$K_IO 
- TPU$K_INPUT 
- TPUSK—OUTPUT 


TPU$K_FILENAME item code is used for specifying the address of a 
string to use as the name of the file you are opening. The length field 
contains the length of this string, and the address field contains the 
address. 


TPU$K_DEFAULTFILE item code is used for assigning a default file 
name to the file being opened. The buffer length field contains the 
length, and the buffer address field contains the address of the default file 
name. 


TPU$K_RELATEDFILE item code is used for specifying a related file 
name for the file being opened. The buffer length field contains the 
length, and the buffer address field contains the address of a string to use 
as the related file name. 


TPU$K_RECORD_ATTR item code specifies that the buffer address field 
contains the value for the record attribute byte in the FAB (FAB$B_RAT) 
used for file creation. 


TPU$K_RECORD_FORM item code ere that the buffer address field 
contains the value for the record format byte in the FAB (FAB$B_RFM) 
used for file creation. 


TPU$K_MAXIMIZE_VER item code specifies that the version number 
of the output file should be one higher than the highest existing version 
number. 


TPU$K_FLUSH item code specifies that the file should have every record 
flushed after it is written. 


TPU$K_FILESIZE item code is used for specifying a value to be used as 
the allocation quantity when creating the file. The value is specified in 
the buffer address field. 
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TPUS$FILEIO 





DESCRIPTION 


Note: 


By default, TPUSFILEIO creates variable-length files with carriage-return 
record attributes (fab$b_rfm = var, fab$b_rat = cr). If you pass to it the 
TPU$K_RECORD_ATTR or TPU$K_RECORD_FORM item, that item is 
used instead. The following combinations of formats and attributes are 
acceptable: 


Format Attributes 


STM,STMLF,STMCR 0,BLK,CR,BLK+CR 
VAR O,BLK,FTN,CR,BLK+FTN,BLK+CR 


All other combinations are converted to VAR format with CR attributes. 


This routine always puts values greater than 511 in the first longword of the 
stream data structure. Because a user-written file [/O routine is restricted to 
the values 0 through 511, you can easily distinguish the file control blocks 
(FCB) this routine fills in from the ones you created. 


VAXTPU uses TPU$FILEIO by default when you use the simplified 
callable interface. When you use the full callable interface, you must 
explicitly invoke TPU$FILEIO or provide your own file I/O routine. 





CONDITION 
VALUES 
RETURNED 
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The TPU$FILEIO routine returns an RMS status code to VAXTPU. The file 
I/O routine is responsible for signaling all errors if any messages are desired. 
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TPUSHANDLER 


TPUSHANDLER VAXTPU Condition Handler 


The TPUSHANDLER routine is VAXTPU’s condition handler. 


The VAXTPU condition handler invokes the Put Message (SYS$PUTMSG) 
system service, passing it the address of TPUSMESSAGE. 














FORMAT TPUSHANDLER _signal_vector, mechanism_vector 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. 
ARGUMENTS _— signal_vector 
VMS usage: arg_list 
type: longword (unsigned) 
access: modify 
mechanism: by reference 
Signal vector. See the VMS System Services Reference Manual for information 
about the signal vector passed to a condition handler. 
mechanism_vector 
VMS usage: arg_list 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
Mechanism vector. See the VMS System Services Reference Manual for 
information about the mechanism vector passed to a condition handler. 
DESCRIPTION — The TPU$MESSAGE routine performs the actual output of the message. The 


Put Message (SYS$PUTMSG) system service only formats the message. It 
gets the settings for the message flags and facility name from the variables 
described in Section 13.1.2. Those values can be modified only by the 
VAXTPU built-in procedure SET. 


If the condition value received by the handler has a FATAL status or does not 
have VAXTPU’s facility code, the condition is resignaled. 


If the condition is TPU$_QUITTING, TPU$_EXITING, or 
TPU$_RECOVERFAIL, a request to UNWIND is made to the establisher of 
the condition handler. 


After handling the message, the condition handler returns with a continue 
status. VAXTPU error message requests are made by signaling a condition 
to indicate which message should be written out. The arguments in the 
signal array are a correctly formatted message argument vector. This vector 
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sometimes contains multiple conditions and formatted ASCII output (FAO) 
arguments for the associated messages. For example, if the editor attempts to 
open a file that does not exist, the VAXTPU message TPU$_NOFILEACCESS 
is signaled. The FAO argument to this message is a string for the name of 
the file. This condition has an error status, followed by the VMS RMS status 
field (STS) and status value field (STV). Because this condition does not have 
a fatal severity, the editor continues after handling the error. 


The editor does not automatically return from TPU$CONTROL. If you call 
the TPU$CONTROL routine, you must explicitly establish a way to regain 
control (for example, using the built-in procedure CALL_USER). Also, if you 
establish your own condition handler but call the VAXTPU handler for certain 
conditions, the default condition handler must be established at the point in 
your program where you want to return control. 


See the Introduction to VMS System Routines for information about the VAX 
Condition Handling Standard. 
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TPUSINITIALIZE Initialize VAXTPU for Editing 


The TPUSINITIALIZE routine initializes VAXTPU for editing. This routine 
allocates global data structures, initializes global variables, and calls the 
appropriate setup routines for each of the major components of the editor, 
including the Virtual File Manager, Screen Manager, and |/O subsystem. 








FORMAT TPUSINITIALIZE callback [,user_arg] 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENT callback 
VMS usage: vector_longword_unsigned 
type: bound procedure value 
access: read only 
mechanism: by descriptor 


Callback routine. The callback argument is the address of a user-written 
routine that returns the address of an item list containing initialization 
parameters or a routine for handling file I/O operations. This callback routine 
must call a parsing routine, which can be TPU$CLIPARSE or a user-written 
parsing routine. 


Callable VAXTPU defines thirteen item codes that can be used for specifying 
initialization parameters. You do not have to arrange the item codes in any 

particular order in the list. Figure 13-3 shows the general format of an item 
descriptor. For information about how to build an item list, refer to the VMS 
programmer’s manual associated with the language you are using. 
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Figure 13-3 Format of an Item Descriptor 


ITEM CODE BUFFER LENGTH 
BUFFER ADDRESS 
RETURN ADDRESS 
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The return address in an item descriptor is usually 0. 


The following item codes are available. 


Item Code Description 


TPU$_OPTIONS Enables the command qualifiers. Ten bits in the 
buffer address field correspond to the various TPU 
command qualifiers. The remaining 22 bits in the 
buffer address field are reserved. 


TPU$_JOURNALFILE Passes the string specified with the /JOURNAL 
qualifier. The buffer length field is the length of the 
string, and the buffer address field is the address of 
the string. This string is available with GET_INFO 
(COMMAND_LINE,“ JOURNAL _FILE”). This string 
may be a null string. 


TPU$_SECTIONFILE Passes the string that is the name of the binary 
initialization file (section file) to be mapped in. The 
buffer length field is the length of the string and the 
buffer address field is the address of the string. The 
VAXTPU CLD file has a default value for this string. 
If the TPUSV_SECTION bit is set, this item code must 
be specified. 


TPU$_OUTPUTFILE Passes the string specified with the /OUTPUT 
qualifier. The buffer length field is the length of 
the string, and the buffer address field specifies the 
address of the string. This string is returned by 
the built-in procedure GET_INFO (COMMAND_LINE, 
“OUTPUT_FILE”). The string may be a null string. 


TPU$_DISPLAYFILE Passes the string specified with the /DISPLAY 
qualifier. The buffer length field is the length of the 
string, and the buffer address field specifies the 
address of the string. 
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Item Code 
TPU$S_COMMANDFILE 


TPU$_FILENAME 


TPU$_FILEIO 


TPU$_CALLUSER 


TPU$_INIT_FILE 


TPU$S_START_LINE 


TPUSINITIALIZE 


Description 


Passes the string specified with the /COMMAND 
qualifier. The buffer length field is the length of 

the string, and the buffer address field is the 
address of the string. This string is returned by 
the built-in procedure GET_INFO (COMMAND_LINE, 
“COMMAND_ FILE”). The string may be a null string. 


Passes the string that is the name of the input file 
specified in the command line. The buffer length 
field specifies the length of this string, and the 
buffer address field specifies its address. This string 
is returned by the built-in procedure GET_INFO 
(COMMAND_LINE, “FILE_NAME"). This file name 
may be a null string. 


Passes the bound procedure value of a routine to be 
used for handling file operations. You may provide 
your own file |/O routine, or you can call TPU$FILEIO, 
the utility routine provided by VAXTPU for handling 
file operations. The buffer address field specifies 

the address of a two-longword vector. The first 
longword of the vector contains the address of 

the routine. The second longword specifies the 
environment value that TPU loads into R1 before 
calling the routine. 


Passes the bound procedure value of the user-written 
routine that the built-in procedure CALL __USER is to 
call. The buffer address field specifies the address 

of a two-longword vector. The first longword of 

the vector contains the address of the routine. The 
second longword specifies the environment value that 
TPU loads into R1 before calling the routine. 


Passes the string specified with the /INITIALIZATION 
qualifier. The buffer length field is the length of the 
string, and the buffer address field is the address 

of the string. This string is returned by the built-in 
procedure GET_INFO (COMMAND_LINE, “INIT_FILE”). 


Passes the starting line number for the edit. The 
buffer address field contains the first of the two 
integer values you specified as part of the /START_ 
POSITION command qualifier. The value is available 
using the built-in procedure GET_INFO (COMMAND... 
LINE,“LINE”). Usually an initialization procedure uses 
this information to set the starting position in the 
main editing buffer. The first line in the buffer is 

line 1. 
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TPUSINITIALIZE 


Item Code 
TPU$_START_CHAR 


TPU$_CONTROLC 


TPU$_DEBUGFILE 


Description 


Passes the starting column position for the edit. 

The buffer address field contains the second of 

the two integer values you specified as part of the 
/START_POSITION command qualifier. The value 

is available. using the built-in procedure GET_INFO 
(COMMAND_LINE, “CHARACTER”). Usually an 
initialization procedure uses this information to set the 
starting position in the main editing buffer. The first 
column on a line corresponds to character 1. 


Passes the bound procedure value of a routine to 
be used for handling CTRL/C ASTs. VAXTPU calls 
the routine when a CTRL/C AST occurs. If the 
routine returns a FALSE value, VAXTPU assumes 
that the CTRL/C has been handled. If the routine 
returns a TRUE value, VAXTPU aborts any currently 
executing VAXTPU procedure. The buffer address 
field specifies the address of a two-longword vector. 
The first longword of the vector contains the address 
of the routine. The second longword specifies the 
environment value that TPU loads into R1 before 
calling the routine. 


Passes the string specified with the /DEBUG 
command qualifier. The buffer length field is the 
length of the string, and the buffer address field is the 
address of the string. 


The following table shows the bits and corresponding masks enabled by the 
item code TPU$K_OPTIONS. 
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Mask 


TPUSM_RECOVER' 
TPU$SM_JOURNAL 
TPUSM_READ 


TPUSM_SECTION 
TPUSM_CREATE 


TPUSM_OUTPUT 
TPUSM_COMMAND 
TPU$SM_DISPLAY 


TPUSM_INIT 


TPUSM_COMMAND_ 
DFLTED 


TPUSM_WRITE 
TPUSM_MODIFY 


TPU$SM_NOMODIFY 


'TPUSM ... 
2TPUSV ... 


indicates a mask. 


indicates a bit item. 


Bit 
TPU$V_RECOVER? 


TPU$SV_JOURNAL 
TPU$V_READ 


TPU$V_SECTION 
TPUSV_CREATE 


TPU$V_OUTPUT 
TPU$V_COMMAND 
TPU$V_DISPLAY 


TPUSV_INIT 


TPU$V_COMMAND_DFLTED 


TPU$SV_WRITE 
TPU$SV_MODIFY 


TPU$V_NOMODIFY 


TPUSINITIALIZE 


Function 


Performs a recovery operation. 
Journals the edit session. 


Makes this a READ_ONLY edit session for 
the main buffer. 

Maps in a binary initialization file (a VAXTPU 
section file) during startup. 


Creates an input file if the one specified 
does not exist. 


Writes the modified input file upon exiting. 
Executes a command file during startup. 


Attempts to use the terminal for screen 
oriented editing and display purposes. 


Indicates the presence of an initialization 
file. 


Indicates whether the user defaulted the 
name of the command line. A setting 
of TRUE means the user did not specify 
a command file. If this bit is set to 
FALSE and the user did not specify a 
file, TPUSINITIALIZE fails. 


Indicates whether /WRITE was specified on 
the command line. 

Indicates whether /MODIFY was specified 
on the command line. 


Indicates whether /NOMODIFY was 
specified on the command line. 


To create the bits, start with the value 0, then use the OR operator on the 
mask (TPU$M ... ) of each item you want to set. Another way to create 
the bits is to treat the 32 bits as a bit vector and set the bit (TPU$V ... ) 
corresponding to the item you want. 


user_arg 
VMS usage: user_arg 


type: longword (unsigned) 
access: read only 
mechanism: 


User argument. The user_arg argument can be used as desired. One 
common use is to pass the address of the item list used by TPUSINITIALIZE. 
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DESCRIPTION This is the first routine that must be called after establishing a condition 
handler. 


This routine initializes the editor according to the information received from 
the callback routine. The initialization routine defaults all file specifications to 
the null string and all options to off. However, it does not default the file I/O 
or call-user routine addresses. 


If you do not specify a section file, the software features of the editor are 





limited. 
CONDITION TPU$_SUCCESS Initializati leted full 
ea t tion eted succ : 
VALUES TPU$_SYSERROR 4 ee ae tt : ee : 
= t t tly. 
RETURNED sys em service did not wor corte y 
TPU$_NONANSICRT The input device (SYS$INPUT) is not a supported 
terminal. 
TPU$S_RESTOREFAIL An error occurred during the restore operation. 
TPU$_NOFILEROUTINE No routine has been established to perform file 
operations. 
TPU$S_INSVIRMEM Insufficient virtual memory exists for the editor to 
initialize. 
TPU$_FAILURE General code for all other errors during initialization. 
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TPUSMESSAGE 


TPUSMESSAGE Write Message String 


The TPUSMESSAGE routine writes error messages and strings using the 
built-in procedure, MESSAGE. 


You can call this routine to have messages written and handled in a 
manner consistent with VAXTPU. This routine should be used only after 
TPUSEXECUTE_INIFILE. 











FORMAT TPU$SMESSAGE $string 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. 

Note: The return status should be ignored because it is intended for use by the 

Put Message (SYS$PUTMSG) system service. 
ARGUMENT string 

VMS usage: char_string 

type: character string 

access: read only 


mechanism: by descriptor 


Formatted message. The string argument is the address of a descriptor of text 
to be written. It must be completely formatted. This routine does not append 
the message prefixes. However, the text is appended to the message buffer if 
one exists. In addition, if the buffer is mapped to a window, the window is 
updated. 
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TPUSPARSEINFO 


TPUS$PARSEINFO Parse Command Line and Build 








Item List 
The TPUSPARSEINFO routine parses a command and builds the item list 
for TPUSINITIALIZE. 
FORMAT TPUSPARSEINFO _fileio, call_user 
RETURNS VMS usage: item_list 
type: _longword (unsigned) 
access: read only 


mechanism: by reference 


The routine returns the address of an item list. 





ARGUMENTS fileio 
VMS usage: vector_longword_unsigned 
type: bound procedure value 
access: read only 
mechanism: by descriptor 


File I/O routine. The fileio argument is the address of a descriptor of a file 
I/O routine. 


call_user 

VMS usage: vector_longword_unsigned 
type: bound procedure value 
access: read only 

mechanism: by descriptor 


Call-user routine. The call_user argument is the address of a descriptor of a 
call-user routine. 





DESCRIPTION — The TPU$PARSEINFO routine parses a command and builds the item list for 
TPUS$INITIALIZE. 


This routine uses the Command Language Interpreter (CLI) routines to parse 
the current command. It makes queries about the command parameters and 
qualifiers that VAXTPU expects. The results of these queries are used to set 
up the proper information in an item list. The addresses of the user routines 
are used for those items in the list. The address of this list is the return value 
of the routine. 
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TPUSTPU 


TPUSTPU Invoke VAXTPU 


The TPU$TPU routine invokes VAXTPU and is equivalent to the DCL 
command EDIT/TPU. 








FORMAT TPUSTPU command 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENT command 
VMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Command string. Note that the verb is TPU instead of EDIT/TPU. The 
command argument is the address of a descriptor of a command line. 





DESCRIPTION This routine takes the command string specified and passes it to the editor. 
VAXTPU uses the information from this command string for initialization 
purposes, just as though you had typed in the command at the DCL level. 


Using the simplified callable interface does not set TPU$CLOSE_SECTION. 
This feature allows you to make multiple calls to TPU$TPU without requiring 
you to open and close the section file on each call. 


If your application parses information that is not related to the operation 
of VAXTPU, make sure the application obtains and uses all non-VAXTPU 
parse information before the application calls PUSEDIT. The reason is 
that TPU$EDIT destroys all parse information obtained and stored before 
TPUS$EDIT was called. 





CONDITION This routine returns any condition value returned by TPU$INITIALIZE, 
VALUES TPU$EXECUTE_INFILE, TPU$CONTROL, and TPU$CLEANUP. 
RETURNED 
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FILEIO 


FILEIO User-Written Routine to Perform File 
Operations 
The user-written FILEIO routine is used to handle VAXTPU file operations. 


The name of this routine can be either your own file |/O routine or the 
name of the VAXTPU file I/O routine (TPUSFILEIO). 








FORMAT FILEIO code, stream, data 
RETURNS VMS usage: cond_value 
type: longword (usigned) 
access: write only 


mechanism: by reference 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS code 
VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item code specifying a VAXTPU function. The code argument is the address 
of a longword containing an item code from VAXTPU, which specifies a 
function to perform. 


stream 

VMS usage: unspecified 

type: longword (unsigned) 
access: modify 


mechanism: by reference 


File description. The stream argument is the address of a data structure 
containing four longwords. This data structure is used to describe the file to 
be manipulated. 


data 

VMS usage: item _list_3 

type: longword (unsigned) 
access: modify 


mechanism: by reference 


Stream data. The data argument is either the address of an item list or the 
address of a descriptor. 


Note: The value of this parameter depends on which item code you specify. 
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FILEIO 





DESCRIPTION The bound procedure value of this routine is specified in the item list built by 
the callback routine. This routine is called to perform file operations. Instead 
of using your own file I/O routine, you can call TPU$FILEIO and pass it 
the parameters for any file operation that you do not want to handle. Note, 
however, that TPU$FILEIO must handle all I/O requests for any file it opens. 
Also, if it does not open the file, it cannot handle any I/O requests for the 
file. In other words, you cannot intermix the file operations between your 
own file I/O routine and the one supplied by VAXTPU. 





CONDITION The condition values returned are determined by the user and should indicate 
VALUES success or failure of the operation. 
RETURNED 
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HANDLER 


HANDLER 


User-Written Condition Handling 
Routine 


The user-written HANDLER routine performs condition handling. 














FORMAT HANDLER = signal_vector, mechanism_vector 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. 
ARGUMENTS _— signal_vector 

VMS usage: arg_list 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Signal vector. See the VMS System Services Reference Manual for information 

about the signal vector passed to a condition handler. 

mechanism_vector 

VMS usage: arg_list 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Mechanism vector. See the VMS System Services Reference Manual for 

information about the mechanism vector passed to a condition handler. 
DESCRIPTION If you need more information about writing condition handlers and the 
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VAX Condition Handling Standard, refer to the Introduction to VMS System 
Routines. 


Instead of writing your own condition handler, you can use the default 
condition handler, TPUSHANDLER. If you want to write your own routine, 
you must call TPUSHANDLER with the same parameters that your routine 
received to handle VAXTPU internal signals. 


VAX Text Processing Utility (VAXTPU) Routines 
INITIALIZE 


INITIALIZE User-Written Initialization Routine 


The user-written initialization callback routine is passed to TPUSINITIALIZE 
as a bound procedure value, and called to supply information needed to 
initialize VAXTPU. 








FORMAT INITIALIZE 

RETURNS VMS usage: item_list 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


This routine returns the address of an item list. 





ARGUMENTS ~ None. 





DESCRIPTION The user written initialization call-back routine is passed to TPU$INITIALIZE 
as a bound procedure value, and called to supply information needed to 
initialize VAXTPU. The initialization call-back routine is called with no 
parameters. It is expected to return the address of an item list containing 
initialization parameters. Because the item list is used outside the scope of 
the initialization call-back routine, it should be allocated in static memory. 


The item list entries are discussed in the section on TPU$INITIALIZE. Most 
of the initialization parameters have a default value; strings default to the null 
string, and flags default to false. The only required initialization parameter 

is the address of a routine for file I/O. If an entry for the file I/O routine 
address is not present in the item list, TPU$INITIALIZE returns with a failure 
status. 
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USER 


USER User-Written Routine Called from a 


VAXTPU Editing Session 


The user-written USER routine allows your program to get control during a 
VAXTPU editing session (for example, to leave the editor temporarily and 
perform a calculation). 


This user-written routine is invoked by the VAXTPU built-in procedure 
CALL _USER. The built-in procedure CALL_USER passes three parameters 
to this routine. These parameters are then passed to the appropriate part 
of your application to be used as specified. (For example, they may be 
used as operands in a calculation within a FORTRAN program.) Using the 
string routines provided by the VMS Run-Time Library, your application 
fills in the stringout parameter in the call-user routine, which returns the 
stringout value to the built-in procedure CALL__USER. 











FORMAT USER integer, stringin, stringout 
RETURNS VMS usage: cond_value 

type: longword (unsigned) — 

access: write only 

mechanism: by value 

Longword condition value. 
ARGUMENTS __ integer 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 
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mechanism: by descriptor 


First parameter to the built-in procedure CALL_USER. This is an input-only 
parameter and must not be modified. 


stringin 

VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor 


Second parameter to the built-in procedure CALL_USER. This is an input- 
only parameter and must not be modified. 
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USER 


stringout 

VMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Return value for the built-in procedure CALL_USER. Your program should 
fill in this descriptor with a dynamic string allocated by the string routines 
provided by the VMS Run-Time Library. The VAXTPU editor frees this string 
when necessary. : 





DESCRIPTION The description of the built-in procedure CALL_USER in the VAX Text 
Processing Utility Manual shows an example of a BASIC program that is a 
call-user routine. 





EXAMPLE 


INTEGER FUNCTION TPU$CALLUSER (x,y,z) 

IMPLICIT NONE 

INTEGER X 

CHARACTER*(*) Y 

STRUCTURE /dynamic/ Z 
INTEGER*2 length 
BYTE dtype 
BYTE class 
INTEGER ptr 

END STRUCTURE 

RECORD /dynamic/ Z 

CHARACTER*80 local_copy 

INTEGER rs,lclen 

INTEGER STR$COPY_DX 

local_copy = '<' // y // '>! 

Iclen = LEN(Y) + 2 


RS = STR$COPY_DX(Z, local_copy(1:1lclen)) 
TPU$CALLUSER = RS 
END 


You can call this FORTRAN program with a VAXTPU procedure. The 
following is an example of one such procedure: 


PROCEDURE MY_CALL 
local status; 
status := CALL_USER (0, 'ABCD'); 
MESSAGE('"'! + minty : 
ENDPROCEDURE 
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Access control list (ACL) 


See also ACL Editor routine 
editing * ACL—3 
manipulating © ACL—1 
Access Control List Editor routine 
See ACL Editor routine 
ACLEDIT$EDIT routine © ACL-3 
ACL Editor routine 
example of use in BLISS programe ACL—1 
introduction ¢ ACL—1 
options available * ACL—4 
ACLEDTS$SECTION logical name 
defined ¢ ACL—5 


Binary data 
compression of ®DCX-—1 
Buckets 
reclaiming with CONV$RECLAIM routine ® 
CONV-18 
reclamation statistics °CONV-—18 


C 


CLI$SDCL_PARSE routine ® CLI-5 
CLISDISPATCH routine ¢ CLI-8 
CLISGET_VALUE routine ® CLI-9 
CLISPRESENT routine ® CLI-12 
CLI routines ; 

See also Command string 

example of use in FORTRAN program ® CLI—1 

introduction @ CLI-1 

list of © CLI-1 

when to use ® CLI-—1 
Command language routines 

See CLI routines 
Command string 

See also CLI routines 

action routine ® CLI-8 








Command string (cont'd.) 
checking for presence of command string 
entities ® CLI-12 
dispatching to action routine ¢ CLI-8 
keyword pathe CLI-12 
labels 
list of label names ® CLI—-11 
obtaining values of command string entities ¢ 
CLI-9 
parsing a DCL command string ® CLI-5 
positional qualifiers © CLI-13 
processing with CLI routines ¢ CLI-1 
prompting for input * CLI-6 
symbol substitution ¢ CLI-5 
Command table . 
with CLI routines ¢ CLI-1, CLI-6 
Context variable 
use with DCX routines ° DCX—17 
CONV$CONVERT routine * CONV—8 
CONV$PASS_FILES routine ®° CONV-11 
CONV$PASS_OPTIONS routine ® CONV—14 
CONV$RECLAIM routine * CONV—18 
CONVERT command 
list of qualifiers * CONV—14 
passing options ® CONV-—14 
passing options in an array * CONV—16 
setting qualifiers ®° CONV—14 
Convert routines 
See CONV routines 
CONV routines 
examples ® CONV—1 to CONV—7 
introduction * CONV—1 
list of eCONV—-1 
using wildcard characters © CONV-—12 


D 


Data compression 
See also DCX routines 
analysis preceding compression ® DCX—14 
compression algorithm 
submitting all data records ° DCX—16 
size of data after compression ® DCX—1 
Data Compression/Expansion routines 


See DCX routines 
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Data expansion ® DCX—23 

See also DCX routines 

initializing ¢ DCX—26 
Data record 

analysis * DCX—13 

compression ® DCX—1 

conversion ¢ CONV—1 

conversion statistics * CONV-—8 

expansion ¢ DCX—1 
DCL command string 

See Command string 
DCX$ANALYZE_DATA routine ® DCX-—12 
DCX$ANALYZE_DONE routine e DCX-14 
DCX$ANALYZE_INIT routine * DCX-15 
DCX$COMPRESS_DATA routine * DCX—18 
DCX$COMPRESS_DONE routine * DCX—20 
DCX$COMPRESS_INIT routine © DCX—2 1 
DCX$EXPAND_DATA routine * DCX—23 
DCX$EXPAND_DONE routine * DCX—25 
DCX$EXPAND_INIT routine © DCX—26 
DCX$MAKE_MAP routine * DCX—28 
DCX routines 

examples * DCX—2 to DCX—11 

introduction * DCX—1 

procedure for use ® DCX—1 

when to use ® DCX—1 

with multiple streams of data records * DCX—1 
Device access , 

controlling through access control lists ® ACL—1 


E 


EDTSEDIT routine * EDT—3 
EDT routines 
examples ®EDT—1 to EDT-—2 
introduction ® EDT—1 
user-written 
FILEIO® EDT—7 
WORKIO ® EDT—1 1 
XLATE ® EDT—13 
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FDLSCREATE routine * FDL—7 
FDLSGENERATE routine * FDL—12 
FDL$PARSE routine e FDL—15 
FDL$SRELEASE routine ® FDL—18 
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FDL routines 

See also FDL specification 

examples ®FDL—1 to FDL-6 

introduction ® FDL—1 
FDL specification 

See also FDL routines 

creating © FDL—7 

default attributes © FDL—16 

generating ® FDL—12 

in character string ® FDL—9 

use of semicolons as delimiters © FDL—1 

parsing * FDL—15 

with CONV routines * CONV—15 
File access 

controlling through access control lists ® ACL—1 
File Definition Language routines 

See FDL routines 
File organization 

changing with CONV routines * CONV-1 
Files . 

Prolog 3 indexed *CONV—1, CONV-18 
File specifications 

with CONV routines ¢ CONV-12 
Full callable interface 

See VAXTPU routines 


G 


Global sections 


controlling access through access control lists ® 
ACL-1 








Images 
compression of ¢DCX—1 

Item list 
with ACL Editor routine ® ACL—3 
with TPU routines © TPU—48 


J 


Job controller 
function e PSM—4 
request to symbiont * SMB—5 








K 


Keyword path 
obtaining values of command string keywords ® 
CLI-9 
referencing command string keywords ® CLI-12 
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LBR$SCLOSE routine * LBR—20 
LBRSDELETE_DATA routine ® LBR—21 
LBR$DELETE_KEY routine * LBR—23 
LBR$FIND routine © LBR-25 
LBR$FLUSH routine ¢ LBR-27 
LBR$GET_HEADER routine * LBR—-29 
LBR$SGET_HELP routine * LBR-31 
LBR$SGET_HISTORY routine ¢ LBR-34 
LBR$GET_INDEX routine © LBR—36 
LBRSGET_RECORD routine * LBR-38 
LBRSINI_CONTROL routine * LBR—40 
LBRSINSERT_KEY routine * LBR—42 
LBR$LOOKUP_KEY routine * LBR—44 
LBRSOPEN routine © LBR—46 
LBRSOUTPUT_HELP routine ¢ LBR—50 
LBRSPUT_END routine e LBR—54 
LBRSPUT_HISTORY routine * LBR-55 
LBR$PUT_RECORD routine ¢ LBR-57 
LBR$SREPLACE_KEY routine © LBR—-59 
LBR$RET_RMSSTV routine ¢ LBR—-61 
LBRSSEARCH routine ¢ LBR-62 
LBR$SSET_INDEX routine * LBR—64 
LBR$SSET_LOCATE routine ¢ LBR—66 
LBRSSET_MODULE routine * LBR-67 
LBR$SET_MOVE routine * LBR-69 
LBR routines 
control index © LBR—7 
current index number 
setting ° LBR-64 
data record 
reading ® LBR-38 
writing ® LBR—57 
end-of-module record 
writing * LBR—54 
examples © LBR—7 to LBR—19 
creating a new library ®LBR—-8 to LBR-—10 
deleting a module from a library ® 
LBR-16 to LBR-19 
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examples (cont’d.) 
extracting a module from a library ® 
LBR—14 to LBR—16 
inserting a module into a library ® 
LBR-10 to LBR-13 
header ® LBR—2 
help text 
outputting * LBR—50 
retrieving © LBR—3 1 
index ¢ LBR—2 
searching ® LBR-62 
introduction ® LBR—1 to LBR-—19 
library 
closing ® LBR—20 
creating ® LBR—46 
opening ® LBR—46 
shareable image * LBR-1 
structure ®LBR—2 to LBR—5 
types © LBR—1 
user-developed ® LBR—1 
library file 
flushing * LBR—27 
library header information 
reading ® LBR—29 
retrieving ® LBR—29 
library index 
getting contents ® LBR—36 
initializing © LBR~40 
searching for key *LBR-36 
library key © LBR-2 
creating ASCII or binary *LBR—47 
deleting * LBR-23 
finding ® LBR-—25 
inserting © LBR—42 
looking up ®°LBR-—44 
replacing ® LBR—59 
library update history record 
retrieving ¢ LBR-34 
locate mode . 
setting record access mode to *LBR—-66 
module ¢ LBR—2 
accessing with RFA ®LBR-—25 
deleting data records ® LBR—2 1 
deleting header ®LBR—2 1 
module header 
reading ®LBR-67 
setting *° LBR—67 
updating © LBR—67 
move mode 
setting record access to ®LBR—69 
summary ®LBR-6 to LBR—7 
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LBR routines (cont’d.) 


update history records 
writing © LBR-55 
virtual memory 
recovering © LBR—27 
VMS RMS status value 
returning ® LBR-6 1 
Librarian routines 
See LBR routines 
Logical name tables 


controlling access through access control lists ® 
ACL-1 
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Mailboxes 


controlling access through access control lists ® 
ACL-1 





N 


NCS$COMPARE routine ¢ NCS—7 
NCS$CONVERT routine ¢ NCS—9 
NCS$END_CF routine © NCS—11 
NCS$END_CS routine * NCS—12 
NCS$GET_CF routine * NCS—13 
NCS$GET_CS routine * NCS—15 
NCS$RESTORE_CF routine * NCS—17 
NCS$RESTORE_CS routine * NCS—19 
NCS$SAVE_CF routine ¢ NCS—2 1 
NCS$SAVE_CS routine * NCS—23 
NCS collating sequence end routine 
See NCS$END_CS routine 
NCS compare strings routine 
See NCS$COMPARE routine 
NCS conversion function end routine 
See NCS$END_CF routine 
NCS convert string routine 
See NCSS$CONVERT routine 
NCS get collating sequence routine 
See NCS$GET_CS routine _ 
NCS get conversion function routine 
See NCS$GET_CF routine 
NCS restore collating sequence routine 
See NCS$RESTORE_CS routine 
NCS restore conversion function routine 
See NCS$RESTORE_CF routine 
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NCS routines 
example of use in FORTRAN program ¢ NCS-3 
example of use in MACRO-32 program * NCS—4 
list of ¢NCS—1 
typical application of *NCS—2 

NCS save collating sequence routine 
See NCS$SAVE_CS routine 

NCS save conversion function routine 
See NCS$SAVE_CF routine 


P 


Print symbiont 
See also Symbiont 
invoking ®* PSM-—22 
Print Symbiont Modification routines 
See PSM routines 
Prolog 3 file 
- creating with CONV routines * CONV—15 
Prolog 3 indexed files 
reclaiming ®* CONV-18 
with Convert/Recilaim Utility ® CONV—1 
Prolog files 
with CONV routines * CONV—15 
Prompt string 
setting with CLISDCL__PARSE ® CLI-7 
PSM$PRINT routine * PSM—22 
PSM$READ_ITEM__DX routine * PSM-—24 
PSMS$REPLACE routine * PSM-26 
PSM$REPORT routine © PSM—3 1 
PSM$_FUNNOTSUP routine e PSM—34 
PSM routines 
examples ® PSM—17 to PSM-—2 14 
introduction ® PSM—1 
user-written 
USER-FORMAT-ROUTINE ¢ PSM-—33 
USER-INPUT-ROUTINE ® PSM-38 
USER-OUTPUT-ROUTINE ® PSM—44 


0 


Queues 
execution ¢ PSM-—3 
generic * PSM-3 











R 


Record 
See Data record 
RMS control blocks 
with FDL routines © FDL—15, FDL—18 


S 


Simplified callable interface 
See VAXTPU routines 
SMBS$CHECK_FOR_MESSAGE routine ® SMB-15 
SMBSINITIALIZE routine © SMB-16 
SMB$READ_MESSAGE routine * SMB-18 
SMB$READ_MESSAGE_ITEM routine * SMB-2 1 
SMB$SEND__TO_JOBCTL routine * SMB-34 
SMB routines 
See also Job Controller 
See also Symbiont 
introduction ® SMB-1 
SORS$STAT routine © SOR—49 
SOR$BEGIN_MERGE routine * SOR—17 
SOR$BEGIN_SORT routine * SOR—24 
SORSDTYPE routine * SOR—30 
SOR$SEND_SORT routine * SOR—33 
SOR$SPASS_FILES routine * SOR—35 
SOR$RELEASE_REC routine © SOR—40 
SOR$SRETURN_REC routine * SOR—42 
SOR$SORT_MERGE routine © SOR—44 
SOR$SPEC_FILE routine * SOR—47 
SOR routines 
examples © SOR-4 to SOR-16 
interface 
file ® SOR-2 
record ® SOR-2 
introduction ® SOR—1 
list of ©SOR-1 
reentrancy 
using context argument ® SOR-3 
Sort/Merge routines 


See SOR routines 
Symbiont 





See also Queues 
allocating memory ® SMB-—4 
carriage control 

processing of *PSM-11 
connecting to a device * SMB—4 


Index 


Symbiont (cont’d.) 
device * PSM-2 
environments ® SMB—5 
function ¢ PSM—4, SMB-—2 
input *PSM-2, SMB—1 
INPSMB.EXE file © SMB—1 
input routines 
demand ¢ PSM-6 
internal logic ® PSM-5 
main format routine * PSM-13 
main input routine ¢ PSM-10 
main output routine * PSM-14 
invoking VMS print symbiont © PSM—22 
job controller 
communication with * SMB—1 
job controller request *SMB-—5 
asynchronous ® SMB-6 
processing ® SMB-1 1 
reading ® SMB-10 
responding ® SMB-13 
synchronous * SMB-—5 
modifying * PSM—7, SMB-—4 
format routine * PSM-—12 
guidelines e PSM—8 
initialization routine © PSM—15 
input routine © PSM—9 
integration of routines © PSM—16 
Output routine * PSM-13 
restrictions © PSM-8 
multistream ¢ SMB-—10 
multithreaded * PSM—3 
output ¢ PSM-—2, SMB-1 
PRTSMB.EXE file © SMB—1 
print symbiont 
internal logic ® PSM—5 
modifying ® PSM-1 
processing it performs ® PSM—1 
user-written ¢ PSM— 1 
processing it performs ® PSM—5 
' process-permanent file ®° SMB—4 
server ® PSM-2, SMB-1 
single stream ®* SMB—10 
stream 
active ® PSM-3 
multiple streams ® PSM-3 
single stream ¢ PSM-—3 
SYSGEN MAXBUF parameter ® PSM—7 
type ° SMB-1 
user-written © SMB—1, SMB-3 
guidelines *° SMB—4 
user-written routines 
interfaces * PSM—7 
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Index 


Symbiont (cont'd.) 
VMS printer * SMB-1 

Symbiont/Job Controller Interface routines 
See SMB routines 

Symbiont thread ¢ PSM—3 


T 


Text 

compression of ®DCX-—1 
Text processing routines 

See VAXTPU routines 
TPUSCLEANUP routine ® TPU-24 
TPUS$CLIPARSE routine * TPU—27 
TPU$SCLOSE_TERMINAL routine * TPU-—28 
TPUSCONTROL routine * TPU—29 
TPU$EDIT routine © TPU-30 
TPUSEXECUTE_COMMAND routine * TPU-32 
TPUSEXECUTE_INIFILE routine © TPU-33 
TPUSFILEIO routine ® TPU-35 
TPUSHANDLER routine * TPU—39 
TPUSINITIALIZE routine © TPU—41 
TPUSMESSAGE routine © TPU-—47 
TPUSPARSEINFO routine * TPU—48 
TPUSTPU routine © TPU-—49 


U 


User-written VAXTPU routines 
See VAXTPU routines 
Utility routines © 1-1 


V 


VAX Text Processing Utility Routines 
See VAXTPU routines 
VAXTPU callable interface 
See VAXTPU routines 
VAXTPU routines 
callable VAXTPU ® TPU-1 
error handling ¢ TPU—3 
full interface e TPU—-2 TPU-—4 
overview ® TPU-1 
simplified interface TPU-2, TPU—4 
condition handler 
condition codes ® TPU—4 
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VAXTPU routines 
condition handler (cont’d.) 
default ¢ TPU—4 
return values © TPU—4 
universal symbols © TPU—4 
examples ¢ TPU-5, TPU-7 to TPU-22 
introduction ¢ TPU—1 
parameter 
bound procedure value * TPU-3 
shareable image ® TPU—1, TPU-3 
constants ¢ TPU-3 
symbols ¢ TPU—3 
user-written 
FILEIO e TPU-50 
HANDLER * TPU-—52 
INITIALIZE ¢ TPU—53 
requirements ® TPU-—7 
USER ¢ TPU-54 
VMS print symbiont 
See Symbiont 


WwW 


Wildcard characters 
with CONV routines © CONV-—12 
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